RFC 7252 Framing

Parse and serialize RFC 7252 PDUs. More...

Detailed Description

Parse and serialize RFC 7252 PDUs.

Module. Specify USEMODULE += unicoap_driver_rfc7252_pdu in your application's Makefile.

This module allows you to use the RFC 7252 parser without having to import the CoAP over UDP Driver or CoAP over DTLS Driver, i.e., without a network backend. This is particularly handy if you want to experiment with unicoap or write tests that don't need the ability to do network I/O.

PDU Format

0                   1                   2                   3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Ver| T |  TKL  |      Code     |          Message ID           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   Token (if any, TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   Options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1|    Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

See also

RFC 7252, Message Format

Parsing
ssize_t	unicoap_pdu_parse_rfc7252 (uint8_t *pdu, size_t size, unicoap_message_t *message, unicoap_message_properties_t *properties)
	Parses RFC 7252 PDU. More...
static ssize_t	unicoap_pdu_parse_rfc7252_result (uint8_t *pdu, size_t size, unicoap_parser_result_t *parsed)
	Helper method for manually parsing a PDU. More...

Serializing
ssize_t	unicoap_pdu_build_header_rfc7252 (uint8_t *header, size_t capacity, const unicoap_message_t *message, const unicoap_message_properties_t *properties)
	Writes RFC 7252 PDU header in the given buffer. More...
static ssize_t	unicoap_pdu_build_rfc7252 (uint8_t *pdu, size_t capacity, const unicoap_message_t *message, const unicoap_message_properties_t *properties)
	Writes RFC 7252 PDU into buffer. More...
static ssize_t	unicoap_pdu_buildv_rfc7252 (uint8_t *header, size_t header_capacity, const unicoap_message_t *message, const unicoap_message_properties_t *properties, iolist_t iolists[UNICOAP_PDU_IOLIST_COUNT])
	Populates the given iolist with header according to RFC 7252, options, and payload. More...

Function Documentation

unicoap_pdu_build_header_rfc7252()

ssize_t unicoap_pdu_build_header_rfc7252	(	uint8_t *	header,
		size_t	capacity,
		const unicoap_message_t *	message,
		const unicoap_message_properties_t *	properties
	)

Writes RFC 7252 PDU header in the given buffer.

Parameters

[in,out]	header	Buffer the header will be written into
	capacity	Number of usable bytes in the header buffer
[in]	message	Message to construct header from (use code or payload_size)
[in]	properties	Message properties to serialize into the header

Returns

Header size

Return values

<tt>-ENOBUFS</tt>

Buffer too small

unicoap_pdu_build_rfc7252()

static ssize_t unicoap_pdu_build_rfc7252 ( uint8_t *  pdu, size_t  capacity, const unicoap_message_t *  message, const unicoap_message_properties_t *  properties  )

inlinestatic

Writes RFC 7252 PDU into buffer.

Parameters

[in,out]	pdu	Buffer
	capacity	PDU buffer capacity
[in]	message	Message
[in]	properties	Message properties containing ID and type

Returns

Size of PDU

Negative integer one error

Return values

<tt>-ENOBUFS</tt>

Buffer too small

Definition at line 1311 of file message.h.

unicoap_pdu_buildv_rfc7252()

static ssize_t unicoap_pdu_buildv_rfc7252 ( uint8_t *  header, size_t  header_capacity, const unicoap_message_t *  message, const unicoap_message_properties_t *  properties, iolist_t  iolists[UNICOAP_PDU_IOLIST_COUNT]  )

inlinestatic

Populates the given iolist with header according to RFC 7252, options, and payload.

Parameters

[in]	header	Header buffer
	header_capacity	Capacity of header buffer
[in]	message	Message containing options and payload
[in]	properties	Message properties containing ID and type
[in,out]	iolists	Buffer of iolists, pre-allocated, size must be be UNICOAP_PDU_IOLIST_COUNT

Precondition

iolists is allocated

Returns

0 on success

Negative integer one error

Return values

<tt>-ENOBUFS</tt>

Buffer too small

Definition at line 1341 of file message.h.

unicoap_pdu_parse_rfc7252()

ssize_t unicoap_pdu_parse_rfc7252	(	uint8_t *	pdu,
		size_t	size,
		unicoap_message_t *	message,
		unicoap_message_properties_t *	properties
	)

Parses RFC 7252 PDU.

Parameters

	pdu	Buffer containing PDU to parse
	size	Size of PDU in bytes
[out]	message	Pre-allocated message to populate, should have options set
[out]	properties	Pre-allocated properties structure to populate

Precondition

message is allocated

properties is allocated

Returns

Zero on success or negative errno on failure

Return values

<tt>-EBADOPT</tt>	Bad option
<tt>-ENOBUFS</tt>	Options buffer in unicoap_message_t::options (unicoap_options_t) too small

Remarks

To allocate everything needed in one go, use unicoap_pdu_parse_rfc7252_result instead.

Note

This function does not mutate or copy the buffer pointed at by pdu. However, it does escape pointers into the buffer pointed at by pdu in message . This is necessary to create a lookup array for options, i.e., to avoid re-parsing the options buffer. You will need to decide whether you treat the message's options as constant or not. This depends on whether the buffer pdu passed to this function is considered constant by you.

As unicoap cannot guarantee you won't add/insert/remove options later, pdu is not qualified by const. That hypothetical const depends on your usage of the message and its options.

unicoap_pdu_parse_rfc7252_result()

static ssize_t unicoap_pdu_parse_rfc7252_result ( uint8_t *  pdu, size_t  size, unicoap_parser_result_t *  parsed  )

inlinestatic

Helper method for manually parsing a PDU.

Parameters

[in]	pdu	PDU buffer
	size	PDU size in bytes
[out]	parsed	Pre-allocated parsed message structure

Precondition

parsed is allocated

Returns

Zero on success or negative errno on failure

Return values

<tt>-EBADOPT</tt>	Bad option
<tt>-ENOBUFS</tt>	Options buffer in unicoap_message_t::options (unicoap_options_t) too small

Note

This function does not mutate or copy the buffer pointed at by pdu. However, it does escape pointers into the buffer pointed at by pdu in message . This is necessary to create a lookup array for options, i.e., to avoid re-parsing the options buffer. You will need to decide whether you treat the message's options as constant or not. This depends on whether the buffer pdu passed to this function is considered constant by you.

As unicoap cannot guarantee you won't add/insert/remove options later, pdu is not qualified by const. That hypothetical const depends on your usage of the message and its options.

Definition at line 1272 of file message.h.