Create and serialize CoAP messages. More...

Detailed Description

Create and serialize CoAP messages.

unicoap_message_t is the central container type for CoAP messages. To see how to access CoAP options, see Options. You may also look at the guide to using CoAP messages

Example

unicoap_message_t message;
 
const char payload[] = "Hello, World!";
unicoap_request_init_string(&message, UNICOAP_METHOD_POST, payload, &options);

You can access the CoAP code through different views, including as ast unicoap_message_t::method, unicoap_message_t::status, or unicoap_message_t::signal number.

Modules
	Options
	Access options from a CoAP message.

	Parsing and Serialization
	Tools for parsing PDUs and serializing messages and options.

	Using Message APIs
	A demo of `unicoap` message APIs.

Files
file	constants.h
	Constants used in CoAP such as option numbers and message codes.

file	message.h
	CoAP Message API.

Data Structures
struct	unicoap_message_t
	Generic CoAP message. More...

struct	unicoap_message_properties_t
	Properties of a CoAP message. More...

CoAP PDUs
enum	unicoap_protocol_version_t { UNICOAP_COAP_VERSION_1 = 1 }
	CoAP version number. More...

#define	UNICOAP_PAYLOAD_MARKER (0xFF)
	Marks the boundary between header and payload.

#define	UNICOAP_ETAG_LENGTH_MAX (8)
	Maximum length of the ETag option in bytes.

#define	UNICOAP_TOKEN_LENGTH_FIXED_WIDTH 4
	Numbers of bits needed to represent token length. More...

RFC 7252 message types
enum	unicoap_rfc7252_message_type_t { UNICOAP_TYPE_CON = 0 , UNICOAP_TYPE_NON = 1 , UNICOAP_TYPE_ACK = 2 , UNICOAP_TYPE_RST = 3 }
	RFC 7252 message type. More...

#define	UNICOAP_RFC7252_MESSAGE_TYPE_FIXED_WIDTH 3
	Number of bits needed to represent unicoap_rfc7252_message_type_t.

Message codes
enum	unicoap_code_class_t { UNICOAP_CODE_CLASS_REQUEST = 0 , UNICOAP_CODE_CLASS_RESPONSE_SUCCESS = 2 , UNICOAP_CODE_CLASS_RESPONSE_CLIENT_FAILURE = 4 , UNICOAP_CODE_CLASS_RESPONSE_SERVER_FAILURE = 5 , UNICOAP_CODE_CLASS_SIGNAL = 7 }
	Message code class. More...

enum	unicoap_method_t { UNICOAP_METHOD_GET = 1 , UNICOAP_METHOD_POST = 2 , UNICOAP_METHOD_PUT = 3 , UNICOAP_METHOD_DELETE = 4 , UNICOAP_METHOD_FETCH = 5 , UNICOAP_METHOD_PATCH = 6 , UNICOAP_METHOD_IPATCH = 7 }
	CoAP request method codes (`0.xx` range) More...

enum	unicoap_signal_t { UNICOAP_SIGNAL_CAPABILITIES_SETTINGS = 1 , UNICOAP_SIGNAL_PING = 2 , UNICOAP_SIGNAL_PONG = 3 , UNICOAP_SIGNAL_RELEASE = 4 , UNICOAP_SIGNAL_ABORT = 5 }
	CoAP Signal Message Codes (`7.xx` range) More...

enum	unicoap_status_t { UNICOAP_STATUS_CREATED = UNICOAP_CODE(RESPONSE_SUCCESS, 1) , UNICOAP_STATUS_DELETED = UNICOAP_CODE(RESPONSE_SUCCESS, 2) , UNICOAP_STATUS_VALID = UNICOAP_CODE(RESPONSE_SUCCESS, 3) , UNICOAP_STATUS_CHANGED = UNICOAP_CODE(RESPONSE_SUCCESS, 4) , UNICOAP_STATUS_CONTENT = UNICOAP_CODE(RESPONSE_SUCCESS, 5) , UNICOAP_STATUS_CONTINUE = UNICOAP_CODE(RESPONSE_SUCCESS, 31) , UNICOAP_STATUS_BAD_REQUEST = UNICOAP_CODE(RESPONSE_CLIENT_FAILURE, 0) , UNICOAP_STATUS_UNAUTHORIZED = UNICOAP_CODE(RESPONSE_CLIENT_FAILURE, 1) , UNICOAP_STATUS_BAD_OPTION = UNICOAP_CODE(RESPONSE_CLIENT_FAILURE, 2) , UNICOAP_STATUS_FORBIDDEN = UNICOAP_CODE(RESPONSE_CLIENT_FAILURE, 3) , UNICOAP_STATUS_PATH_NOT_FOUND = UNICOAP_CODE(RESPONSE_CLIENT_FAILURE, 4) , UNICOAP_STATUS_METHOD_NOT_ALLOWED = UNICOAP_CODE(RESPONSE_CLIENT_FAILURE, 5) , UNICOAP_STATUS_NOT_ACCEPTABLE = UNICOAP_CODE(RESPONSE_CLIENT_FAILURE, 6) , UNICOAP_STATUS_REQUEST_ENTITY_INCOMPLETE = UNICOAP_CODE(RESPONSE_CLIENT_FAILURE, 8) , UNICOAP_STATUS_CONFLICT = UNICOAP_CODE(RESPONSE_CLIENT_FAILURE, 9) , UNICOAP_STATUS_PRECONDITION_FAILED = UNICOAP_CODE(RESPONSE_CLIENT_FAILURE, 12) , UNICOAP_STATUS_REQUEST_ENTITY_TOO_LARGE = UNICOAP_CODE(RESPONSE_CLIENT_FAILURE, 13) , UNICOAP_STATUS_UNSUPPORTED_CONTENT_FORMAT = UNICOAP_CODE(RESPONSE_CLIENT_FAILURE, 15) , UNICOAP_STATUS_UNPROCESSABLE_ENTITY = UNICOAP_CODE(RESPONSE_CLIENT_FAILURE, 22) , UNICOAP_STATUS_TOO_MANY_REQUESTS = UNICOAP_CODE(RESPONSE_CLIENT_FAILURE, 29) , UNICOAP_STATUS_INTERNAL_SERVER_ERROR = UNICOAP_CODE(RESPONSE_SERVER_FAILURE, 0) , UNICOAP_STATUS_NOT_IMPLEMENTED = UNICOAP_CODE(RESPONSE_SERVER_FAILURE, 1) , UNICOAP_STATUS_BAD_GATEWAY = UNICOAP_CODE(RESPONSE_SERVER_FAILURE, 2) , UNICOAP_STATUS_SERVICE_UNAVAILABLE = UNICOAP_CODE(RESPONSE_SERVER_FAILURE, 3) , UNICOAP_STATUS_GATEWAY_TIMEOUT = UNICOAP_CODE(RESPONSE_SERVER_FAILURE, 4) , UNICOAP_STATUS_PROXYING_NOT_SUPPORTED = UNICOAP_CODE(RESPONSE_SERVER_FAILURE, 5) }
	CoAP response status codes. More...

#define	UNICOAP_CODE_EMPTY (0)
	Code for an empty CoAP message.

CoAP message
enum	unicoap_payload_representation_t { UNICOAP_PAYLOAD_CONTIGUOUS = 0 , UNICOAP_PAYLOAD_NONCONTIGUOUS = 1 }
	A type indicating how a message's payload is represented. More...

const char *	unicoap_string_from_rfc7252_type (unicoap_rfc7252_message_type_t type)
	Returns a null-terminated label for the CoAP over UDP/DTLS message type. More...

static uint8_t *	unicoap_message_t::unicoap_message_payload_get (unicoap_message_t *message)
	Retrieves contiguous message payload, if available. More...

static void	unicoap_message_t::unicoap_message_payload_set (unicoap_message_t message, uint8_t payload, size_t size)
	Assigns the given message a contiguous payload. More...

static iolist_t *	unicoap_message_t::unicoap_message_payload_get_chunks (unicoap_message_t *message)
	Retrieves noncontiguous message payload, if available. More...

static void	unicoap_message_t::unicoap_message_payload_set_chunks (unicoap_message_t message, iolist_t chunks)
	Assigns the given message a noncontiguous payload. More...

void	unicoap_message_t::unicoap_message_payload_append_chunk (unicoap_message_t message, iolist_t chunk)
	Appends a payload chunk to a message. More...

static size_t	unicoap_message_t::unicoap_message_payload_get_size (const unicoap_message_t *message)
	Retrieves payload size, regardless of payload representation. More...

bool	unicoap_message_t::unicoap_message_payload_is_empty (const unicoap_message_t *message)
	Determines whether message has any payload. More...

ssize_t	unicoap_message_t::unicoap_message_payload_copy (const unicoap_message_t message, uint8_t buffer, size_t capacity)
	Copies payload into given buffer. More...

ssize_t	unicoap_message_t::unicoap_message_payload_make_contiguous (unicoap_message_t message, uint8_t buffer, size_t capacity)
	Copies noncontiguous payload into contiguous storage buffer. More...

static uint8_t *	unicoap_message_t::unicoap_message_options_data (const unicoap_message_t *message)
	Retrieves options storage buffer. More...

static size_t	unicoap_message_t::unicoap_message_options_size (const unicoap_message_t *message)
	Retrieves total size of options in buffer. More...

CoAP code
static uint8_t	unicoap_code_class (uint8_t code)
	Reads the code class number encoded in the given code. More...

static uint8_t	unicoap_code_detail (uint8_t code)
	Reads the code detail number encoded in the given code. More...

int	unicoap_print_code (uint8_t code, char *string)
	Prints a `c.dd` class-detail string into the given buffer. More...

const char *	unicoap_string_from_code (uint8_t code)
	Returns label for given CoAP message code. More...

const char *	unicoap_string_from_code_class (uint8_t code)
	Returns label for given CoAP message code class. More...

Message initializers
static unicoap_message_t	unicoap_message_alloc_empty (uint8_t code)
	Creates message with no payload and no options. More...

static unicoap_message_t	unicoap_message_alloc (uint8_t code, uint8_t *payload, size_t payload_size)
	Creates message with no payload and no options. More...

static unicoap_message_t	unicoap_message_alloc_string (uint8_t code, const char *payload)
	Creates message with payload from null-terminated but no options. More...

static unicoap_message_t	unicoap_message_alloc_with_options (uint8_t code, uint8_t payload, size_t payload_size, unicoap_options_t options)
	Creates message with byte payload and options. More...

static unicoap_message_t	unicoap_message_alloc_string_with_options (uint8_t code, const char payload, unicoap_options_t options)
	Creates message with payload from null-terminated UTF-8 string and options. More...

static void	unicoap_message_t::unicoap_message_init_empty (unicoap_message_t *message, uint8_t code)
	Initializes message with no payload and no options. More...

static void	unicoap_message_t::unicoap_message_init (unicoap_message_t message, uint8_t code, uint8_t payload, size_t payload_size)
	Initializes message with payload but no options. More...

static void	unicoap_message_t::unicoap_message_init_string (unicoap_message_t message, uint8_t code, const char payload)
	Initializes message with payload from null-terminated UTF-8 string but no options. More...

static void	unicoap_message_t::unicoap_message_init_with_options (unicoap_message_t message, uint8_t code, uint8_t payload, size_t payload_size, unicoap_options_t *options)
	Initializes message with byte payload and options. More...

static void	unicoap_message_t::unicoap_message_init_string_with_options (unicoap_message_t message, uint8_t code, const char payload, unicoap_options_t *options)
	Initializes message with payload from null-terminated UTF-8 string and options. More...

Signaling messages
static bool	unicoap_message_is_signal (uint8_t code)
	Determines if the given message's code is a a signaling code. More...

const char *	unicoap_string_from_signal (unicoap_signal_t signal)
	Returns label for given CoAP signal code. More...

static unicoap_signal_t	unicoap_message_t::unicoap_message_get_signal (const unicoap_message_t *message)
	Retrieves signal code from given signal message. More...

static void	unicoap_message_t::unicoap_message_set_signal (unicoap_message_t *message, unicoap_signal_t signal)
	Sets signal code of given signal message. More...

Request messages
static bool	unicoap_message_is_request (uint8_t code)
	Determines if the the given message's code is a a request code. More...

const char *	unicoap_string_from_method (unicoap_method_t method)
	Obtains label for given request method. More...

static unicoap_message_t	unicoap_request_alloc_empty (unicoap_method_t method)
	Creates request with no payload and no options. More...

static unicoap_message_t	unicoap_request_alloc (unicoap_method_t method, uint8_t *payload, size_t payload_size)
	Creates request with no payload and no options. More...

static unicoap_message_t	unicoap_request_alloc_string (unicoap_method_t method, const char *payload)
	Creates request with payload from null-terminated UTF-8 string but no options. More...

static unicoap_message_t	unicoap_request_alloc_with_options (unicoap_method_t method, uint8_t payload, size_t payload_size, unicoap_options_t options)
	Creates request with byte payload and options. More...

static unicoap_message_t	unicoap_request_alloc_string_with_options (unicoap_method_t method, const char payload, unicoap_options_t options)
	Creates request with payload from null-terminated UTF-8 string and options. More...

static unicoap_method_t	unicoap_message_t::unicoap_request_get_method (const unicoap_message_t *request)
	Obtains request method from the given message's code. More...

static void	unicoap_message_t::unicoap_request_set_method (unicoap_message_t *request, unicoap_method_t method)
	Sets request method. More...

static void	unicoap_message_t::unicoap_request_init_empty (unicoap_message_t *request, unicoap_method_t method)
	Initializes request with no payload and no options. More...

static void	unicoap_message_t::unicoap_request_init (unicoap_message_t request, unicoap_method_t method, uint8_t payload, size_t payload_size)
	Initializes request with payload but no options. More...

static void	unicoap_message_t::unicoap_request_init_string (unicoap_message_t request, unicoap_method_t method, const char payload)
	Initializes request with payload from null-terminated UTF-8 string but no options. More...

static void	unicoap_message_t::unicoap_request_init_with_options (unicoap_message_t request, unicoap_method_t method, uint8_t payload, size_t payload_size, unicoap_options_t *options)
	Initializes request with byte payload and options. More...

static void	unicoap_message_t::unicoap_request_init_string_with_options (unicoap_message_t request, unicoap_method_t method, const char payload, unicoap_options_t *options)
	Initializes request with payload from null-terminated UTF-8 string and options. More...

Response messages
bool	unicoap_message_is_response (uint8_t code)
	Determines if the the given message's code is a a response code. More...

const char *	unicoap_string_from_status (unicoap_status_t status)
	Generates short descriptive label from CoAP status code. More...

static unicoap_message_t	unicoap_response_alloc_empty (unicoap_status_t status)
	Creates response with no payload and no options. More...

static unicoap_message_t	unicoap_response_alloc (unicoap_status_t status, uint8_t *payload, size_t payload_size)
	Creates response with no payload and no options. More...

static unicoap_message_t	unicoap_response_alloc_string (unicoap_status_t status, const char *payload)
	Creates response with payload from null-terminated UTF-8 string but no options. More...

static unicoap_message_t	unicoap_response_alloc_with_options (unicoap_status_t status, uint8_t payload, size_t payload_size, unicoap_options_t options)
	Creates response with string byte and options. More...

static unicoap_message_t	unicoap_response_alloc_string_with_options (unicoap_status_t status, const char payload, unicoap_options_t options)
	Creates response with payload from null-terminated UTF-8 string and options. More...

static unicoap_status_t	unicoap_message_t::unicoap_response_get_status (const unicoap_message_t *response)
	Obtains response status from the given message's code. More...

static void	unicoap_message_t::unicoap_response_set_status (unicoap_message_t *response, unicoap_status_t status)
	Sets response status. More...

static void	unicoap_message_t::unicoap_response_init_empty (unicoap_message_t *response, unicoap_status_t status)
	Initializes response with no payload and no options. More...

static void	unicoap_message_t::unicoap_response_init (unicoap_message_t response, unicoap_status_t status, uint8_t payload, size_t payload_size)
	Initializes response with payload but no options. More...

static void	unicoap_message_t::unicoap_response_init_string (unicoap_message_t response, unicoap_status_t status, const char payload)
	Initializes response with payload from null-terminated UTF-8 string but no options. More...

static void	unicoap_message_t::unicoap_response_init_with_options (unicoap_message_t response, unicoap_status_t status, uint8_t payload, size_t payload_size, unicoap_options_t *options)
	Initializes response with byte payload and options. More...

static void	unicoap_message_t::unicoap_response_init_string_with_options (unicoap_message_t response, unicoap_status_t status, const char payload, unicoap_options_t *options)
	Initializes response with payload from null-terminated UTF-8 string and options. More...

Macro Definition Documentation

◆ UNICOAP_TOKEN_LENGTH_FIXED_WIDTH

#define UNICOAP_TOKEN_LENGTH_FIXED_WIDTH 4

Numbers of bits needed to represent token length.

Corresponds to TKL field width. As per RFC 7252, token lengths greater than 8 bytes must not be used. Hence, no more than 4 bits are needed, which is why TKL fields never occupy more than 4 bits.

Use this constant to define bitfields containing a token length member.

Definition at line 67 of file constants.h.

Enumeration Type Documentation

◆ unicoap_code_class_t

enum unicoap_code_class_t

Message code class.

Corresponds to the upper three bits of a message code

Enumerator
UNICOAP_CODE_CLASS_REQUEST	Message class for requests.
UNICOAP_CODE_CLASS_RESPONSE_SUCCESS	Message class for success responses.
UNICOAP_CODE_CLASS_RESPONSE_CLIENT_FAILURE	Message class for responses indicating a client error.
UNICOAP_CODE_CLASS_RESPONSE_SERVER_FAILURE	Message class for responses indicating a server error.
UNICOAP_CODE_CLASS_SIGNAL	Signaling message.

Definition at line 121 of file constants.h.

◆ unicoap_method_t

enum unicoap_method_t

CoAP request method codes (0.xx range)

Enumerator
UNICOAP_METHOD_GET	`GET` request (no paylod)
UNICOAP_METHOD_POST	`POST` request (resource processes payload)
UNICOAP_METHOD_PUT	`PUT` request (update resource with payload)
UNICOAP_METHOD_DELETE	`DELETE` request (no payload, remove resource)
UNICOAP_METHOD_FETCH	`FETCH` request (RFC 8132)
UNICOAP_METHOD_PATCH	`PATCH` request (RFC 8132)
UNICOAP_METHOD_IPATCH	`iPATCH` request (RFC 8132)

Definition at line 141 of file constants.h.

◆ unicoap_payload_representation_t

enum unicoap_payload_representation_t

A type indicating how a message's payload is represented.

Enumerator
UNICOAP_PAYLOAD_CONTIGUOUS	Contiguous payload buffer.
UNICOAP_PAYLOAD_NONCONTIGUOUS	iolist_t payload vector

Definition at line 45 of file message.h.

◆ unicoap_protocol_version_t

enum unicoap_protocol_version_t

CoAP version number.

Enumerator
UNICOAP_COAP_VERSION_1	Identifier for CoAP version 1 (RFC 7252)

Definition at line 41 of file constants.h.

◆ unicoap_rfc7252_message_type_t

enum unicoap_rfc7252_message_type_t

RFC 7252 message type.

Enumerator
UNICOAP_TYPE_CON	A confirmable message.
UNICOAP_TYPE_NON	A non-confirmable message.
UNICOAP_TYPE_ACK	An acknowledgement message.
UNICOAP_TYPE_RST	An reset message.

Definition at line 83 of file constants.h.

◆ unicoap_signal_t

enum unicoap_signal_t

CoAP Signal Message Codes (7.xx range)

Each of these signaling messages has their own option number space.

See also: RFC 8323, Section 5.1

Enumerator
UNICOAP_SIGNAL_CAPABILITIES_SETTINGS	Capabilities and settings message (CSM) See also RFC 8323
UNICOAP_SIGNAL_PING	Ping message. See also RFC 8323
UNICOAP_SIGNAL_PONG	Pong message. See also RFC 8323
UNICOAP_SIGNAL_RELEASE	Release message. See also RFC 8323
UNICOAP_SIGNAL_ABORT	Abort message. See also [RFC 8323])(https://datatracker.ietf.org/doc/html/rfc8323#section-5.6)

Definition at line 177 of file constants.h.

◆ unicoap_status_t

enum unicoap_status_t

CoAP response status codes.

Enumerator
UNICOAP_STATUS_CREATED	2.01 Create See also RFC 7252
UNICOAP_STATUS_DELETED	2.02 Deleted See also RFC7252
UNICOAP_STATUS_VALID	2.03 Valid See also RFC 7252
UNICOAP_STATUS_CHANGED	2.04 Changed See also RFC 7252
UNICOAP_STATUS_CONTENT	2.05 Content See also RFC 7252
UNICOAP_STATUS_CONTINUE	2.31 Continue See also RFC 7252
UNICOAP_STATUS_BAD_REQUEST	4.00 Bad Request See also RFC 7252
UNICOAP_STATUS_UNAUTHORIZED	4.01 Unauthorized See also RFC 7252
UNICOAP_STATUS_BAD_OPTION	4.02 Bad Option See also RFC 7252
UNICOAP_STATUS_FORBIDDEN	4.03 Forbidden See also RFC 7252
UNICOAP_STATUS_PATH_NOT_FOUND	4.04 Not Found See also RFC 7252
UNICOAP_STATUS_METHOD_NOT_ALLOWED	4.05 Method Not Allowed See also RFC 7252
UNICOAP_STATUS_NOT_ACCEPTABLE	4.06 Not Acceptable See also [RFC 7252](https://datatracker.ietf.org/doc/html/rfc7252#section-5.9.2.7
UNICOAP_STATUS_REQUEST_ENTITY_INCOMPLETE	4.08 Request Entity Incomplete See also RFC 7252
UNICOAP_STATUS_CONFLICT	4.09 Conflict See also RFC 7252
UNICOAP_STATUS_PRECONDITION_FAILED	4.12 Precondition Failed See also RFC 7252
UNICOAP_STATUS_REQUEST_ENTITY_TOO_LARGE	4.13 Request Entity Too Large See also RFC 7252 RFC 7959
UNICOAP_STATUS_UNSUPPORTED_CONTENT_FORMAT	4.15 Unsupported Content Format See also RFC 7252
UNICOAP_STATUS_UNPROCESSABLE_ENTITY	Unprocessable Entity. See also RFC 8132
UNICOAP_STATUS_TOO_MANY_REQUESTS	4.29 Too Many Requests See also RFC 8516
UNICOAP_STATUS_INTERNAL_SERVER_ERROR	5.00 Internal Server Error See also RFC7252
UNICOAP_STATUS_NOT_IMPLEMENTED	5.01 Not Implemented See also RFC7252
UNICOAP_STATUS_BAD_GATEWAY	5.02 Bad Gateway See also RFC 7252
UNICOAP_STATUS_SERVICE_UNAVAILABLE	5.03 Service Unavailable See also RFC 7252
UNICOAP_STATUS_GATEWAY_TIMEOUT	5.04 Gateway Timeout See also RFC 7252
UNICOAP_STATUS_PROXYING_NOT_SUPPORTED	5.05 Proxying Not Supported See also RFC7252

Definition at line 215 of file constants.h.

Function Documentation

◆ unicoap_code_class()

static uint8_t unicoap_code_class ( uint8_t code )

inlinestatic

Reads the code class number encoded in the given code.

A message code is divided into the three class bits and five detail bits. The class bits form a single-digit number, the detail bits represents a two-digit number. Hence, message codes are written as c.dd. In the following listing, C is a class bit and D is a detail bit. The C bits represent the class c, and the D bits form the detail number d.

  Bit
  7 6 5   4   3 2 1 0
[ C C C | D   D D D D ]

Parameters

code	Message code

Returns: Code class number

See also: unicoap_code_detail

Definition at line 393 of file message.h.

◆ unicoap_code_detail()

static uint8_t unicoap_code_detail ( uint8_t code )

inlinestatic

Reads the code detail number encoded in the given code.

A message code is divided into the three class bits and five detail bits. The class bits form a single-digit number, the detail bits represents a two-digit number. Hence, message codes are written as c.dd. In the following listing, C is a class bit and D is a detail bit. The C bits represent the class c, and the D bits form the detail number d.

  Bit
  7 6 5   4   3 2 1 0
[ C C C | D   D D D D ]

Parameters

code	Message code

Returns: Code detail number

See also: unicoap_code_class

Definition at line 416 of file message.h.

◆ unicoap_message_alloc()

static unicoap_message_t unicoap_message_alloc	(	uint8_t	code,
		uint8_t *	payload,
		size_t	payload_size
	)

inlinestatic

Creates message with no payload and no options.

Parameters

	code	Message code
[in]	payload	Payload bytes (nullable)
	payload_size	Payload size

Returns: Message structure

Definition at line 506 of file message.h.

◆ unicoap_message_alloc_empty()

static unicoap_message_t unicoap_message_alloc_empty ( uint8_t code )

inlinestatic

Creates message with no payload and no options.

Parameters

code	Message code

Returns: Message structure

Definition at line 476 of file message.h.

◆ unicoap_message_alloc_string()

static unicoap_message_t unicoap_message_alloc_string	(	uint8_t	code,
		const char *	payload
	)

inlinestatic

Creates message with payload from null-terminated but no options.

Parameters

	code	Message code
[in]	payload	Payload string (nullable), must be null-terminated

Returns: Message structure

Definition at line 536 of file message.h.

◆ unicoap_message_alloc_string_with_options()

static unicoap_message_t unicoap_message_alloc_string_with_options	(	uint8_t	code,
		const char *	payload,
		unicoap_options_t *	options
	)

inlinestatic

Creates message with payload from null-terminated UTF-8 string and options.

Parameters

	code	Message code
[in]	payload	Payload string (nullable), must be null-terminated
[in]	options	Message options, must be pre-allocated and pre-initialized

Returns: Message structure

Precondition: options is allocated

Definition at line 612 of file message.h.

◆ unicoap_message_alloc_with_options()

static unicoap_message_t unicoap_message_alloc_with_options	(	uint8_t	code,
		uint8_t *	payload,
		size_t	payload_size,
		unicoap_options_t *	options
	)

inlinestatic

Creates message with byte payload and options.

Parameters

	code	Message code
[in]	payload	Payload bytes (nullable)
	payload_size	Payload size
[in]	options	Message options, must be pre-allocated and pre-initialized

Returns: Message structure

Precondition: options is allocated

Definition at line 574 of file message.h.

◆ unicoap_message_get_signal()

static unicoap_signal_t unicoap_message_get_signal ( const unicoap_message_t * message )

inline

Retrieves signal code from given signal message.

Parameters

[in] message CoAP signal

Returns: Message code as unicoap_signal_t

Definition at line 649 of file message.h.

◆ unicoap_message_init()

static void unicoap_message_init	(	unicoap_message_t *	message,
		uint8_t	code,
		uint8_t *	payload,
		size_t	payload_size
	)

inline

Initializes message with payload but no options.

Parameters

[in,out]	message	Pre-allocated message structure
	code	Message code
[in]	payload	Payload bytes (nullable)
	payload_size	Payload size

Precondition: message is allocated

Definition at line 490 of file message.h.

◆ unicoap_message_init_empty()

static void unicoap_message_init_empty	(	unicoap_message_t *	message,
		uint8_t	code
	)

inline

Initializes message with no payload and no options.

Parameters

	code	Message code
[in,out]	message	Pre-allocated message structure

Precondition: message is allocated

Definition at line 463 of file message.h.

◆ unicoap_message_init_string()

static void unicoap_message_init_string	(	unicoap_message_t *	message,
		uint8_t	code,
		const char *	payload
	)

inline

Initializes message with payload from null-terminated UTF-8 string but no options.

Parameters

[in,out]	message	Pre-allocated message structure
	code	Message code
[in]	payload	Payload string (nullable), must be null-terminated

Precondition: message is allocated

Definition at line 521 of file message.h.

◆ unicoap_message_init_string_with_options()

static void unicoap_message_init_string_with_options	(	unicoap_message_t *	message,
		uint8_t	code,
		const char *	payload,
		unicoap_options_t *	options
	)

inline

Initializes message with payload from null-terminated UTF-8 string and options.

Parameters

[in,out]	message	Pre-allocated message structure
	code	Message code
[in]	payload	Payload string (nullable), must be null-terminated
[in]	options	Message options, must be pre-allocated and pre-initialized

Precondition: message is allocated; options is allocated

Definition at line 595 of file message.h.

◆ unicoap_message_init_with_options()

static void unicoap_message_init_with_options	(	unicoap_message_t *	message,
		uint8_t	code,
		uint8_t *	payload,
		size_t	payload_size,
		unicoap_options_t *	options
	)

inline

Initializes message with byte payload and options.

Parameters

[in,out]	message	Pre-allocated message structure
	code	Message code
[in]	payload	Payload bytes (nullable)
	payload_size	Payload size
[in]	options	Message options, must be pre-allocated and pre-initialized

Precondition: message is allocated; options is allocated

Definition at line 555 of file message.h.

◆ unicoap_message_is_request()

static bool unicoap_message_is_request ( uint8_t code )

inlinestatic

Determines if the the given message's code is a a request code.

This function internally reads the code class encoded in the code's upper three bits.

Parameters

code	Message code

Returns: A boolean value indicating whether the given message is a request

Definition at line 690 of file message.h.

◆ unicoap_message_is_response()

bool unicoap_message_is_response ( uint8_t code )

Determines if the the given message's code is a a response code.

This function internally reads the code class encoded in the code's upper three bits.

Parameters

code	Message code

Returns: A boolean value indicating whether the given message is a response

◆ unicoap_message_is_signal()

static bool unicoap_message_is_signal ( uint8_t code )

inlinestatic

Determines if the given message's code is a a signaling code.

This function internally reads the code class encoded in the code's upper three bits.

Parameters

code	Message code

Returns: A boolean value indicating whether the given message is a signal

Definition at line 637 of file message.h.

◆ unicoap_message_options_data()

static uint8_t * unicoap_message_options_data ( const unicoap_message_t * message )

inline

Retrieves options storage buffer.

Parameters

[in] message Message

Returns: Pointer to first byte of storage buffer, can be NULL

Definition at line 353 of file message.h.

◆ unicoap_message_options_size()

static size_t unicoap_message_options_size ( const unicoap_message_t * message )

inline

Retrieves total size of options in buffer.

Parameters

[in] message Message

Returns: Size of options in buffer in bytes

Definition at line 364 of file message.h.

◆ unicoap_message_payload_append_chunk()

void unicoap_message_payload_append_chunk	(	unicoap_message_t *	message,
		iolist_t *	chunk
	)

Appends a payload chunk to a message.

Precondition: Message's payload must be noncontiguous

Parameters

	message	Message
[in]	chunk	Payload chunk

◆ unicoap_message_payload_copy()

ssize_t unicoap_message_payload_copy	(	const unicoap_message_t *	message,
		uint8_t *	buffer,
		size_t	capacity
	)

Copies payload into given buffer.

Parameters

	message	Message whose payload to copy
[in,out]	buffer	Destination payload buffer
	capacity	Capacity of `buffer` in bytes

Returns: Payload size in bytes, -ENOBUFS if given buffer is too small

You can call this method regardless of whether payload is stored contiguously or noncontiguously.

◆ unicoap_message_payload_get()

static uint8_t * unicoap_message_payload_get ( unicoap_message_t * message )

inline

Retrieves contiguous message payload, if available.

Precondition: Payload representation must be UNICOAP_PAYLOAD_CONTIGUOUS

Parameters

message Message to retrieve payload buffer from

Returns: Payload buffer pointer

Definition at line 181 of file message.h.

◆ unicoap_message_payload_get_chunks()

static iolist_t * unicoap_message_payload_get_chunks ( unicoap_message_t * message )

inline

Retrieves noncontiguous message payload, if available.

Precondition: Payload representation must be UNICOAP_PAYLOAD_NONCONTIGUOUS

Parameters

message Message to retrieve payload vector from

Returns: Payload vector pointer

Definition at line 212 of file message.h.

◆ unicoap_message_payload_get_size()

static size_t unicoap_message_payload_get_size ( const unicoap_message_t * message )

inline

Retrieves payload size, regardless of payload representation.

Parameters

message Message whose payload size to compute (if noncontiguous payload) or retrieve (contiguous payload).

Returns: Payload size in bytes

Note: This function calls iolist_size if payload is noncontiguous, thus iterates over all iolist elements. The complexity is $O(n)$.

Definition at line 251 of file message.h.

◆ unicoap_message_payload_is_empty()

bool unicoap_message_payload_is_empty ( const unicoap_message_t * message )

Determines whether message has any payload.

Parameters

message Message with payload in question

Returns: A boolean indicating whether any payload bytes are present

The given message may still have a buffer or iolist vector associated, yet this function returns false if the buffer or vector is empty.

◆ unicoap_message_payload_make_contiguous()

ssize_t unicoap_message_payload_make_contiguous	(	unicoap_message_t *	message,
		uint8_t *	buffer,
		size_t	capacity
	)

Copies noncontiguous payload into contiguous storage buffer.

Precondition: None, if payload is already contiguous, this method does not copy.

Parameters

[in,out]	message	Message whose payload to make contiguous
[in,out]	buffer	Destination payload buffer
	capacity	Capacity of `buffer` in bytes

Returns: Payload size in bytes, -ENOBUFS if given buffer is too small

◆ unicoap_message_payload_set()

static void unicoap_message_payload_set	(	unicoap_message_t *	message,
		uint8_t *	payload,
		size_t	size
	)

inline

Assigns the given message a contiguous payload.

Parameters

	message	Message
[in]	payload	Payload buffer
	size	Size of `payload` in bytes

Definition at line 195 of file message.h.

◆ unicoap_message_payload_set_chunks()

static void unicoap_message_payload_set_chunks	(	unicoap_message_t *	message,
		iolist_t *	chunks
	)

inline

Assigns the given message a noncontiguous payload.

Parameters

	message	Message
[in]	chunks	Payload vector

Definition at line 225 of file message.h.

◆ unicoap_message_set_signal()

static void unicoap_message_set_signal	(	unicoap_message_t *	message,
		unicoap_signal_t	signal
	)

inline

Sets signal code of given signal message.

Parameters

[in,out]	message	CoAP signal
	signal	Signal code

Definition at line 661 of file message.h.

◆ unicoap_print_code()

int unicoap_print_code	(	uint8_t	code,
		char *	string
	)

Prints a c.dd class-detail string into the given buffer.

Precondition: string must have a capacity of at least 4 characters

Parameters

	code	Message code
[out]	string	Buffer to write string into

◆ unicoap_request_alloc()

static unicoap_message_t unicoap_request_alloc	(	unicoap_method_t	method,
		uint8_t *	payload,
		size_t	payload_size
	)

inlinestatic

Creates request with no payload and no options.

Parameters

	method	Request method
[in]	payload	Payload bytes (nullable)
	payload_size	Payload size

Returns: Request structure

Definition at line 776 of file message.h.

◆ unicoap_request_alloc_empty()

static unicoap_message_t unicoap_request_alloc_empty ( unicoap_method_t method )

inlinestatic

Creates request with no payload and no options.

Parameters

method Request method

Returns: Request structure

Definition at line 748 of file message.h.

◆ unicoap_request_alloc_string()

static unicoap_message_t unicoap_request_alloc_string	(	unicoap_method_t	method,
		const char *	payload
	)

inlinestatic

Creates request with payload from null-terminated UTF-8 string but no options.

Parameters

	method	Request method
[in]	payload	Payload string (nullable), must be null-terminated

Returns: Request structure

Definition at line 803 of file message.h.

◆ unicoap_request_alloc_string_with_options()

static unicoap_message_t unicoap_request_alloc_string_with_options	(	unicoap_method_t	method,
		const char *	payload,
		unicoap_options_t *	options
	)

inlinestatic

Creates request with payload from null-terminated UTF-8 string and options.

Parameters

	method	Request method
[in]	payload	Payload string (nullable), must be null-terminated
[in]	options	Message options, must be pre-allocated and pre-initialized

Returns: Request structure

Precondition: options is allocated

Definition at line 874 of file message.h.

◆ unicoap_request_alloc_with_options()

static unicoap_message_t unicoap_request_alloc_with_options	(	unicoap_method_t	method,
		uint8_t *	payload,
		size_t	payload_size,
		unicoap_options_t *	options
	)

inlinestatic

Creates request with byte payload and options.

Parameters

	method	Request method
[in]	payload	Payload bytes (nullable)
	payload_size	Payload size
[in]	options	Message options, must be pre-allocated and pre-initialized

Returns: Request structure

Precondition: options is allocated

Definition at line 838 of file message.h.

◆ unicoap_request_get_method()

static unicoap_method_t unicoap_request_get_method ( const unicoap_message_t * request )

inline

Obtains request method from the given message's code.

Parameters

[in] request Request message, pre-initialized

Returns: Message code as unicoap_method_t

Definition at line 702 of file message.h.

◆ unicoap_request_init()

static void unicoap_request_init	(	unicoap_message_t *	request,
		unicoap_method_t	method,
		uint8_t *	payload,
		size_t	payload_size
	)

inline

Initializes request with payload but no options.

Parameters

[in,out]	request	Pre-allocated request structure
	method	Request method
[in]	payload	Payload bytes (nullable)
	payload_size	Payload size

Precondition: request is allocated

Definition at line 763 of file message.h.

◆ unicoap_request_init_empty()

static void unicoap_request_init_empty	(	unicoap_message_t *	request,
		unicoap_method_t	method
	)

inline

Initializes request with no payload and no options.

Parameters

	method	Request method
[in,out]	request	Pre-allocated request structure

Precondition: request is allocated

Definition at line 738 of file message.h.

◆ unicoap_request_init_string()

static void unicoap_request_init_string	(	unicoap_message_t *	request,
		unicoap_method_t	method,
		const char *	payload
	)

inline

Initializes request with payload from null-terminated UTF-8 string but no options.

Parameters

[in,out]	request	Pre-allocated request structure
	method	Request method
[in]	payload	Payload string (nullable), must be null-terminated

Precondition: request is allocated

Definition at line 791 of file message.h.

◆ unicoap_request_init_string_with_options()

static void unicoap_request_init_string_with_options	(	unicoap_message_t *	request,
		unicoap_method_t	method,
		const char *	payload,
		unicoap_options_t *	options
	)

inline

Initializes request with payload from null-terminated UTF-8 string and options.

Parameters

[in,out]	request	Pre-allocated request structure
	method	Request method
[in]	payload	Payload string (nullable), must be null-terminated
[in]	options	Message options, must be pre-allocated and pre-initialized

Precondition: request is allocated; options is allocated

Definition at line 857 of file message.h.

◆ unicoap_request_init_with_options()

static void unicoap_request_init_with_options	(	unicoap_message_t *	request,
		unicoap_method_t	method,
		uint8_t *	payload,
		size_t	payload_size,
		unicoap_options_t *	options
	)

inline

Initializes request with byte payload and options.

Parameters

[in,out]	request	Pre-allocated request structure
	method	Request method
[in]	payload	Payload bytes (nullable)
	payload_size	Payload size
[in]	options	Message options, must be pre-allocated and pre-initialized

Precondition: request is allocated; options is allocated

Definition at line 821 of file message.h.

◆ unicoap_request_set_method()

static void unicoap_request_set_method	(	unicoap_message_t *	request,
		unicoap_method_t	method
	)

inline

Sets request method.

Parameters

[in,out]	request	Request message, pre-allocated
	method	Request method to set

Precondition: request is allocated

Definition at line 715 of file message.h.

◆ unicoap_response_alloc()

static unicoap_message_t unicoap_response_alloc	(	unicoap_status_t	status,
		uint8_t *	payload,
		size_t	payload_size
	)

inlinestatic

Creates response with no payload and no options.

Parameters

	status	Response status
[in]	payload	Payload bytes (nullable)
	payload_size	Payload size

Returns: Response structure

Definition at line 976 of file message.h.

◆ unicoap_response_alloc_empty()

static unicoap_message_t unicoap_response_alloc_empty ( unicoap_status_t status )

inlinestatic

Creates response with no payload and no options.

Parameters

status Response status

Returns: Response structure

Definition at line 948 of file message.h.

◆ unicoap_response_alloc_string()

static unicoap_message_t unicoap_response_alloc_string	(	unicoap_status_t	status,
		const char *	payload
	)

inlinestatic

Creates response with payload from null-terminated UTF-8 string but no options.

Parameters

	status	Response status
[in]	payload	Payload string (nullable), must be null-terminated

Returns: Response structure

Definition at line 1003 of file message.h.

◆ unicoap_response_alloc_string_with_options()

static unicoap_message_t unicoap_response_alloc_string_with_options	(	unicoap_status_t	status,
		const char *	payload,
		unicoap_options_t *	options
	)

inlinestatic

Creates response with payload from null-terminated UTF-8 string and options.

Parameters

	status	Response status
[in]	payload	Payload string (nullable), must be null-terminated
[in]	options	Message options, must be pre-allocated and pre-initialized

Returns: Response structure

Precondition: options is allocated

Definition at line 1075 of file message.h.

◆ unicoap_response_alloc_with_options()

static unicoap_message_t unicoap_response_alloc_with_options	(	unicoap_status_t	status,
		uint8_t *	payload,
		size_t	payload_size,
		unicoap_options_t *	options
	)

inlinestatic

Creates response with string byte and options.

Parameters

	status	Response status
[in]	payload	Payload bytes (nullable)
	payload_size	Payload size
[in]	options	Message options, must be pre-allocated and pre-initialized

Returns: Response structure

Precondition: options is allocated

Definition at line 1039 of file message.h.

◆ unicoap_response_get_status()

static unicoap_status_t unicoap_response_get_status ( const unicoap_message_t * response )

inline

Obtains response status from the given message's code.

Parameters

[in] response Response message, pre-initialized

Returns: Message code as unicoap_status_t

Definition at line 905 of file message.h.

◆ unicoap_response_init()

static void unicoap_response_init	(	unicoap_message_t *	response,
		unicoap_status_t	status,
		uint8_t *	payload,
		size_t	payload_size
	)

inline

Initializes response with payload but no options.

Parameters

[in,out]	response	Pre-allocated response structure
	status	Response status
[in]	payload	Payload bytes (nullable)
	payload_size	Payload size

Precondition: response is allocated

Definition at line 963 of file message.h.

◆ unicoap_response_init_empty()

static void unicoap_response_init_empty	(	unicoap_message_t *	response,
		unicoap_status_t	status
	)

inline

Initializes response with no payload and no options.

Parameters

	status	Response status
[in,out]	response	Pre-allocated response structure

Precondition: response is allocated

Definition at line 938 of file message.h.

◆ unicoap_response_init_string()

static void unicoap_response_init_string	(	unicoap_message_t *	response,
		unicoap_status_t	status,
		const char *	payload
	)

inline

Initializes response with payload from null-terminated UTF-8 string but no options.

Parameters

[in,out]	response	Pre-allocated response structure
	status	Response status
[in]	payload	Payload string (nullable), must be null-terminated

Precondition: response is allocated

Definition at line 991 of file message.h.

◆ unicoap_response_init_string_with_options()

static void unicoap_response_init_string_with_options	(	unicoap_message_t *	response,
		unicoap_status_t	status,
		const char *	payload,
		unicoap_options_t *	options
	)

inline

Initializes response with payload from null-terminated UTF-8 string and options.

Parameters

[in,out]	response	Pre-allocated response structure
	status	Response status
[in]	payload	Payload string (nullable), must be null-terminated
[in]	options	Message options, must be pre-allocated and pre-initialized

Precondition: response is allocated; options is allocated

Definition at line 1058 of file message.h.

◆ unicoap_response_init_with_options()

static void unicoap_response_init_with_options	(	unicoap_message_t *	response,
		unicoap_status_t	status,
		uint8_t *	payload,
		size_t	payload_size,
		unicoap_options_t *	options
	)

inline

Initializes response with byte payload and options.

Parameters

[in,out]	response	Pre-allocated response structure
	status	Response status
[in]	payload	Payload bytes (nullable)
	payload_size	Payload size
[in]	options	Message options, must be pre-allocated and pre-initialized

Precondition: response is allocated; options is allocated

Definition at line 1021 of file message.h.

◆ unicoap_response_set_status()

static void unicoap_response_set_status	(	unicoap_message_t *	response,
		unicoap_status_t	status
	)

inline

Sets response status.

Parameters

[in,out]	response	Response message, pre-allocated
	status	Response status to set

Precondition: response is allocated

Definition at line 918 of file message.h.

◆ unicoap_string_from_code()

const char* unicoap_string_from_code ( uint8_t code )

Returns label for given CoAP message code.

Parameters

code	CoAP message code

Returns: Label, such as "POST", "Abort", or "Bad Request"; "?" if code is unknown

◆ unicoap_string_from_code_class()

const char* unicoap_string_from_code_class ( uint8_t code )

Returns label for given CoAP message code class.

Parameters

code	CoAP message code

Returns: Label, "REQ", "RES", "SIGNAL", or "EMPTY"; "?" if code class is unknown

◆ unicoap_string_from_method()

const char* unicoap_string_from_method ( unicoap_method_t method )

Obtains label for given request method.

Returns "GET", "PUT", "POST", ...

Parameters

method Request method to return label for

Returns: String label

◆ unicoap_string_from_rfc7252_type()

const char* unicoap_string_from_rfc7252_type ( unicoap_rfc7252_message_type_t type )

Returns a null-terminated label for the CoAP over UDP/DTLS message type.

Parameters

type	CoAP over UDP/DTLS message.

Returns: Message type label, never NULL

Return values

<tt>"NON"</tt>	A non-confirmable message
<tt>"CON"</tt>	A confirmable message
<tt>"ACK"</tt>	An acknowledgement message
<tt>"RST"</tt>	A reset message
<tt>"?"</tt>	Unknown message type

◆ unicoap_string_from_signal()

const char* unicoap_string_from_signal ( unicoap_signal_t signal )

Returns label for given CoAP signal code.

Parameters

signal CoAP signal code

Returns: Label, such as "Ping", "Abort", or "CSM"; "?" if code is unknown

◆ unicoap_string_from_status()

const char* unicoap_string_from_status ( unicoap_status_t status )

Generates short descriptive label from CoAP status code.

Parameters

status CoAP status code

Returns: Status string or "?" if status code is unknown

Detailed Description

Example

Modules

Files

Data Structures

CoAP PDUs

RFC 7252 message types

Message codes

CoAP message

CoAP code

Message initializers

Signaling messages

Request messages

Response messages

Macro Definition Documentation

◆ UNICOAP_TOKEN_LENGTH_FIXED_WIDTH

Enumeration Type Documentation

◆ unicoap_code_class_t

◆ unicoap_method_t

◆ unicoap_payload_representation_t

◆ unicoap_protocol_version_t

◆ unicoap_rfc7252_message_type_t

◆ unicoap_signal_t

◆ unicoap_status_t

Function Documentation

◆ unicoap_code_class()

◆ unicoap_code_detail()

◆ unicoap_message_alloc()

◆ unicoap_message_alloc_empty()

◆ unicoap_message_alloc_string()

◆ unicoap_message_alloc_string_with_options()

◆ unicoap_message_alloc_with_options()

◆ unicoap_message_get_signal()

◆ unicoap_message_init()

◆ unicoap_message_init_empty()

◆ unicoap_message_init_string()

◆ unicoap_message_init_string_with_options()

◆ unicoap_message_init_with_options()

◆ unicoap_message_is_request()

◆ unicoap_message_is_response()

◆ unicoap_message_is_signal()

◆ unicoap_message_options_data()

◆ unicoap_message_options_size()

◆ unicoap_message_payload_append_chunk()

◆ unicoap_message_payload_copy()

◆ unicoap_message_payload_get()

◆ unicoap_message_payload_get_chunks()

◆ unicoap_message_payload_get_size()

◆ unicoap_message_payload_is_empty()

◆ unicoap_message_payload_make_contiguous()

◆ unicoap_message_payload_set()

◆ unicoap_message_payload_set_chunks()

◆ unicoap_message_set_signal()

◆ unicoap_print_code()

◆ unicoap_request_alloc()

◆ unicoap_request_alloc_empty()

◆ unicoap_request_alloc_string()

◆ unicoap_request_alloc_string_with_options()

◆ unicoap_request_alloc_with_options()

◆ unicoap_request_get_method()

◆ unicoap_request_init()

◆ unicoap_request_init_empty()

◆ unicoap_request_init_string()

◆ unicoap_request_init_string_with_options()

◆ unicoap_request_init_with_options()

◆ unicoap_request_set_method()

◆ unicoap_response_alloc()

◆ unicoap_response_alloc_empty()

◆ unicoap_response_alloc_string()

◆ unicoap_response_alloc_string_with_options()

◆ unicoap_response_alloc_with_options()

◆ unicoap_response_get_status()

◆ unicoap_response_init()

◆ unicoap_response_init_empty()

◆ unicoap_response_init_string()

◆ unicoap_response_init_string_with_options()

◆ unicoap_response_init_with_options()

◆ unicoap_response_set_status()

◆ unicoap_string_from_code()

◆ unicoap_string_from_code_class()