Retrieve and manipulate generic repeatable and non-repeatable options in CoAP messages. More...

Detailed Description

Retrieve and manipulate generic repeatable and non-repeatable options in CoAP messages.

Data Structures
struct	unicoap_options_iterator_t
	The iterator you use to retrieve option values in-order. More...

Repeatable options
Options that can occur more than once in a CoAP message
int	unicoap_options_t::unicoap_options_add (unicoap_options_t options, unicoap_option_number_t number, const uint8_t value, size_t value_size)
	Adds a repeatable option with the given value. More...

int	unicoap_options_t::unicoap_options_add_values_joined (unicoap_options_t options, unicoap_option_number_t number, const uint8_t buffer, size_t size, uint8_t separator)
	Splits the given value into separate values and adds them as option values. More...

ssize_t	unicoap_options_t::unicoap_options_copy_values_joined (const unicoap_options_t options, unicoap_option_number_t number, uint8_t buffer, size_t capacity, uint8_t separator)
	Copies the values of all options with the given number joined by the given separator. More...

int	unicoap_options_t::unicoap_options_remove_all (unicoap_options_t *options, unicoap_option_number_t number)
	Removes all options with the given number, if any. More...

Non-repeatable options
Options that occur only once
ssize_t	unicoap_options_t::unicoap_options_get (const unicoap_options_t options, unicoap_option_number_t number, const uint8_t *value)
	Retrieves the value of the option with given value, if present. More...

ssize_t	unicoap_options_t::unicoap_options_copy_value (const unicoap_options_t options, unicoap_option_number_t number, uint8_t dest, size_t capacity)
	Copies the value of the option with given value, if present, into a buffer. More...

int	unicoap_options_t::unicoap_options_set (unicoap_options_t options, unicoap_option_number_t number, const uint8_t value, size_t value_size)
	Sets the option with the given number. More...

static int	unicoap_options_t::unicoap_options_remove (unicoap_options_t *options, unicoap_option_number_t number)
	Removes option with the given number, if present. More...

Enumerating options
static void	unicoap_options_iterator_t::unicoap_options_iterator_init (unicoap_options_iterator_t iterator, unicoap_options_t options)
	Initializes the given iterator structure. More...

ssize_t	unicoap_options_iterator_t::unicoap_options_get_next (unicoap_options_iterator_t iterator, unicoap_option_number_t number, const uint8_t **value)
	Gets the next option provided by the given iterator. More...

ssize_t	unicoap_options_iterator_t::unicoap_options_get_next_by_number (unicoap_options_iterator_t iterator, unicoap_option_number_t number, const uint8_t *value)
	Gets the next option with the given number, potentially skipping any options in between. More...

ssize_t	unicoap_options_iterator_t::unicoap_options_get_next_query_by_name (unicoap_options_iterator_t iterator, unicoap_option_number_t number, const char name, const char **value)
	Gets the next query option matching the given name, potentially skipping any options in between. More...

void	unicoap_options_t::unicoap_options_dump_all (const unicoap_options_t *options)
	Iterates and dumps all options using `printf` More...

Strings
static int	unicoap_options_t::unicoap_options_set_string (unicoap_options_t options, unicoap_option_number_t number, const char string, size_t count)
	Sets a non-repeatable option to the given string value. More...

static int	unicoap_options_t::unicoap_options_add_string (unicoap_options_t options, unicoap_option_number_t number, const char string, size_t count)
	Adds a repeatable option with the given string value. More...

Unsigned integers
static ssize_t	unicoap_options_t::unicoap_options_get_uint32 (const unicoap_options_t options, unicoap_option_number_t number, uint32_t uint)
	Retrieves an unsigned option value that takes up at most 4 bytes. More...

static ssize_t	unicoap_options_t::unicoap_options_get_uint24 (const unicoap_options_t options, unicoap_option_number_t number, uint32_t uint)
	Retrieves an unsigned option value that takes up at most 3 bytes. More...

static ssize_t	unicoap_options_t::unicoap_options_get_uint16 (const unicoap_options_t options, unicoap_option_number_t number, uint16_t uint)
	Retrieves an unsigned option value that takes up at most 2 bytes. More...

static ssize_t	unicoap_options_t::unicoap_options_get_uint8 (const unicoap_options_t options, unicoap_option_number_t number, uint8_t uint)
	Retrieves an unsigned option value that takes up at most one bytes. More...

int	unicoap_options_t::unicoap_options_set_uint (unicoap_options_t *options, unicoap_option_number_t number, uint32_t value)
	Sets the option with the given number to the unsigned integer value passed. More...

int	unicoap_options_t::unicoap_options_add_uint (unicoap_options_t *options, unicoap_option_number_t number, uint32_t value)
	Adds a repeatable option with the given unsigned integer value. More...

Function Documentation

◆ unicoap_options_add()

int unicoap_options_add	(	unicoap_options_t *	options,
		unicoap_option_number_t	number,
		const uint8_t *	value,
		size_t	value_size
	)

Adds a repeatable option with the given value.

Use this function to insert multiple options with the same number but potentially different values.

Parameters

[in]	options	Options
	number	Option number
[in]	value	Option value to set
	value_size	Number of bytes the `value` is made up of

Returns: Negative integer on error

Return values

Zero	on success
<tt>-ENOBUFS</tt>	if options buffer lacks sufficient capacity to add option

◆ unicoap_options_add_string()

static int unicoap_options_add_string	(	unicoap_options_t *	options,
		unicoap_option_number_t	number,
		const char *	string,
		size_t	count
	)

inline

Adds a repeatable option with the given string value.

Use this function to insert multiple options with the same number but potentially different values.

Parameters

[in]	options	Options
	number	Option number
[in]	string	String option value to set
	count	Number of characters the string is made up of, excluding null-terminator, or zero, which triggers a `strlen` call

Specify the number of characters or zero to let unicoap determine the string length.

Returns: Zero on success or negative integer on error

Return values

<tt>-ENOBUFS</tt> if options buffer lacks sufficient capacity to add option

Definition at line 730 of file options.h.

◆ unicoap_options_add_uint()

int unicoap_options_add_uint	(	unicoap_options_t *	options,
		unicoap_option_number_t	number,
		uint32_t	value
	)

Adds a repeatable option with the given unsigned integer value.

Use this function to insert multiple options with the same number but potentially different values.

Unsigned option values in CoAP are variable in length, i.e., uints are not zero-padded. A zero may be represented by a zero-length option value.

Parameters

[in]	options	Options
	number	Option number
	value	Unsigned integer option value

Returns: Zero on success or negative integer on error

Return values

<tt>-ENOBUFS</tt> if options buffer lacks sufficient capacity to add option

◆ unicoap_options_add_values_joined()

int unicoap_options_add_values_joined	(	unicoap_options_t *	options,
		unicoap_option_number_t	number,
		const uint8_t *	buffer,
		size_t	size,
		uint8_t	separator
	)

Splits the given value into separate values and adds them as option values.

Use this function to insert multiple options with the same number but potentially different values. The buffer will be sliced everywhere the separator occurs. This is the same as calling unicoap_options_add for each chunk inbeetween separator bytes.

Parameters

[in]	options	Options
	number	Option number
[in]	buffer	Option values separated by `separator`
	size	Number of bytes the value is made up of
	separator	Separator byte used to indicate boundaries between option values

Returns: Negative integer on error or zero on success

Return values

<tt>-ENOBUFS</tt> if options buffer lacks sufficient capacity to add options

Note: A leading separator in buffer will be ignored by this function.

◆ unicoap_options_copy_value()

ssize_t unicoap_options_copy_value	(	const unicoap_options_t *	options,
		unicoap_option_number_t	number,
		uint8_t *	dest,
		size_t	capacity
	)

Copies the value of the option with given value, if present, into a buffer.

Parameters

[in]	options	Options
	number	Option number
[in,out]	dest	Destination buffer where option value will be copied into
	capacity	Number of usable bytes in the `dest` buffer

Returns: Size of option value (zero or more bytes) or negative errno if the get operation failed

Return values

<tt>-ENOENT</tt>	Options not found
<tt>-EBADOPT</tt>	Options buffer is corrupted
<tt>-ENOBUFS</tt>	if `dest` lacks sufficient capacity to store value

◆ unicoap_options_copy_values_joined()

ssize_t unicoap_options_copy_values_joined	(	const unicoap_options_t *	options,
		unicoap_option_number_t	number,
		uint8_t *	buffer,
		size_t	capacity,
		uint8_t	separator
	)

Copies the values of all options with the given number joined by the given separator.

Use this API with repeatable options

Parameters

[in]	options	Options
	number	Option number
[in,out]	buffer	Buffer to copy string value into, must be large enough to carry characters.
	capacity	Number of usable bytes in `dest`
	separator	Separator to insert between option values.

Returns: Size of generated byte sequence, including separators or negative integer on error

Return values

<tt>-ENOBUFS</tt> if buffer lacks sufficient capacity to store string

Precondition: capacity is greater than zero.

Warning: This function does not create a null-terminated C string.

◆ unicoap_options_dump_all()

void unicoap_options_dump_all ( const unicoap_options_t * options )

Iterates and dumps all options using printf

Parameters

[in] options Options

◆ unicoap_options_get()

ssize_t unicoap_options_get	(	const unicoap_options_t *	options,
		unicoap_option_number_t	number,
		const uint8_t **	value
	)

Retrieves the value of the option with given value, if present.

Parameters

[in]	options	Options
	number	Option number
[in,out]	value	Option value. Provide a pointer to a an `uint8_t` pointer, which may be `NULL`.

Returns: Size of option value (zero or more bytes) or negative errno if the get operation failed

Return values

<tt>-ENOENT</tt>	Options not found
<tt>-EBADOPT</tt>	Options buffer is corrupted

◆ unicoap_options_get_next()

ssize_t unicoap_options_get_next	(	unicoap_options_iterator_t *	iterator,
		unicoap_option_number_t *	number,
		const uint8_t **	value
	)

Gets the next option provided by the given iterator.

This is a zero-copy API.

Parameters

[in,out]	iterator	Option iterator
[out]	number	The number of the next option
[out]	value	A pointer to next option's value

Returns: Positive size of option value on success or negative integer on error instead

Return values

<tt>-1</tt>	if the iterator is finished
<tt>-EBADOPT</tt>	Options buffer is corrupted

◆ unicoap_options_get_next_by_number()

ssize_t unicoap_options_get_next_by_number	(	unicoap_options_iterator_t *	iterator,
		unicoap_option_number_t	number,
		const uint8_t **	value
	)

Gets the next option with the given number, potentially skipping any options in between.

This is a zero-copy API. Use this function to iterate over specific options that may occur more than once.

Parameters

[in,out]	iterator	Option iterator
	number	The option number to look out for
[out]	value	A pointer to next option's value

Returns: Positive size of option value or negative integer on error

Return values

<tt>-1</tt>	if the iterator is finished
<tt>-EBADOPT</tt>	Options buffer is corrupted

◆ unicoap_options_get_next_query_by_name()

ssize_t unicoap_options_get_next_query_by_name	(	unicoap_options_iterator_t *	iterator,
		unicoap_option_number_t	number,
		const char *	name,
		const char **	value
	)

Gets the next query option matching the given name, potentially skipping any options in between.

Use this function to iterate over specific options that may occur more than once.

This method splits query values at the = character. It is used both for Uri-Query and Location-Query.

Parameters

[in,out]	iterator	Option iterator
[out]	number	Option number
[in]	name	Name of UTF-8 query parameter to find
[out]	value	Pointer to a UTF-8 string variable

Returns: Positive size of option value or Negative integer on error

Return values

<tt>-EBADOPT</tt>	Option is corrupted
<tt>-1</tt>	if the iterator is finished

Warning: value will not be null-terminated.

Note: This function does not perform Unicode normalization when comparing strings. Instead, memcmp is used. This is compliant with RFC 7252, Section 3.2

◆ unicoap_options_get_uint16()

static ssize_t unicoap_options_get_uint16	(	const unicoap_options_t *	options,
		unicoap_option_number_t	number,
		uint16_t *	uint
	)

inline

Retrieves an unsigned option value that takes up at most 2 bytes.

Unsigned option values in CoAP are variable in length, i.e., uints are not zero-padded. A zero may be represented by a zero-length option value.

Parameters

[in]	options	Options
	number	Option number
[in,out]	uint	Provide a pointer to an allocated 16-bit unsigned integer, will have been filled after function has returned

Returns: Number of bytes occupied by the unsigned integer in the option value or negative integer on error

Return values

<tt>-ENOENT</tt>	Option not found
<tt>-EBADOPT</tt>	Option is corrupted

Definition at line 829 of file options.h.

◆ unicoap_options_get_uint24()

static ssize_t unicoap_options_get_uint24	(	const unicoap_options_t *	options,
		unicoap_option_number_t	number,
		uint32_t *	uint
	)

inline

Retrieves an unsigned option value that takes up at most 3 bytes.

Unsigned option values in CoAP are variable in length, i.e., uints are not zero-padded. A zero may be represented by a zero-length option value.

Parameters

[in]	options	Options
	number	Option number
[in,out]	uint	Provide a pointer to an allocated 32-bit unsigned integer, will have been filled after function has returned

Returns: Number of bytes occupied by the unsigned integer in the option value or negative integer on error

Return values

<tt>-ENOENT</tt>	Option not found
<tt>-EBADOPT</tt>	Option is corrupted

Definition at line 806 of file options.h.

◆ unicoap_options_get_uint32()

static ssize_t unicoap_options_get_uint32	(	const unicoap_options_t *	options,
		unicoap_option_number_t	number,
		uint32_t *	uint
	)

inline

Retrieves an unsigned option value that takes up at most 4 bytes.

Unsigned option values in CoAP are variable in length, i.e., uints are not zero-padded. A zero may be represented by a zero-length option value.

Parameters

[in]	options	Options
	number	Option number
[in,out]	uint	Provide a pointer to an allocated 32-bit unsigned integer, will have been filled after function has returned

Returns: Number of bytes occupied by the unsigned integer in the option value or negative integer on error

Return values

<tt>-ENOENT</tt>	Option not found
<tt>-EBADOPT</tt>	Option is corrupted

Definition at line 783 of file options.h.

◆ unicoap_options_get_uint8()

static ssize_t unicoap_options_get_uint8	(	const unicoap_options_t *	options,
		unicoap_option_number_t	number,
		uint8_t *	uint
	)

inline

Retrieves an unsigned option value that takes up at most one bytes.

Unsigned option values in CoAP are variable in length, i.e., uints are not zero-padded. A zero may be represented by a zero-length option value.

Parameters

[in]	options	Options
	number	Option number
[in,out]	uint	Provide a pointer to an allocated 8-bit unsigned integer, will have been filled after function has returned

Returns: Number of bytes occupied by the unsigned integer in the option value or negative integer on error

Return values

<tt>-ENOENT</tt>	Option not found
<tt>-EBADOPT</tt>	Option is corrupted
<tt>-ENOBUFS</tt>	Option value was bigger than 1 byte

Definition at line 856 of file options.h.

◆ unicoap_options_iterator_init()

static void unicoap_options_iterator_init	(	unicoap_options_iterator_t *	iterator,
		unicoap_options_t *	options
	)

inline

Initializes the given iterator structure.

Parameters

[in,out]	iterator	Option iterator struct to initialize
[in]	options	Options to iterate over

Definition at line 601 of file options.h.

◆ unicoap_options_remove()

static int unicoap_options_remove	(	unicoap_options_t *	options,
		unicoap_option_number_t	number
	)

inline

Removes option with the given number, if present.

Parameters

options	Options
number	Option number

Note: If no option with the specified number exists, this function will return zero.

Returns: Zero on success or negative integer on error instead

Definition at line 552 of file options.h.

◆ unicoap_options_remove_all()

int unicoap_options_remove_all	(	unicoap_options_t *	options,
		unicoap_option_number_t	number
	)

Removes all options with the given number, if any.

Use this API with repeatable options

Parameters

[in,out]	options	Options
	number	Option number

Note: If no option with the specified number exists, this function will return zero.

Returns: Negative integer on error or zero on success

◆ unicoap_options_set()

int unicoap_options_set	(	unicoap_options_t *	options,
		unicoap_option_number_t	number,
		const uint8_t *	value,
		size_t	value_size
	)

Sets the option with the given number.

Parameters

[in,out]	options	Options
	number	Option number
[in]	value	Option value
	value_size	Number of bytes the `value` is made up of

Returns: Zero on success or egative integer on error instead

Return values

<tt>-ENOBUFS</tt> if options storage buffer lacks sufficient capacity to set option

◆ unicoap_options_set_string()

static int unicoap_options_set_string	(	unicoap_options_t *	options,
		unicoap_option_number_t	number,
		const char *	string,
		size_t	count
	)

inline

Sets a non-repeatable option to the given string value.

Parameters

[in]	options	Options
	number	Option number
[in]	string	String option value to set
	count	Number of characters the string is made up of, excluding null-terminator, or zero, which triggers a `strlen` call

Specify the number of characters or zero to let unicoap determine the string length.

Returns: Zero on success or negative integer on error otherwise

Return values

<tt>-ENOBUFS</tt> if options buffer lacks sufficient capacity to set option

Definition at line 704 of file options.h.

◆ unicoap_options_set_uint()

int unicoap_options_set_uint	(	unicoap_options_t *	options,
		unicoap_option_number_t	number,
		uint32_t	value
	)

Sets the option with the given number to the unsigned integer value passed.

Unsigned option values in CoAP are variable in length, i.e., uints are not zero-padded. A zero may be represented by a zero-length option value.

Parameters

[in]	options	Options
	number	Option number
	value	Unsigned integer option value

Returns: Zero on success or negative integer on error

Return values

<tt>-ENOBUFS</tt> if options buffer lacks sufficient capacity to set option

Detailed Description

Data Structures

Repeatable options

Non-repeatable options

Enumerating options

Strings

Unsigned integers

Function Documentation

◆ unicoap_options_add()

◆ unicoap_options_add_string()

◆ unicoap_options_add_uint()

◆ unicoap_options_add_values_joined()

◆ unicoap_options_copy_value()

◆ unicoap_options_copy_values_joined()

◆ unicoap_options_dump_all()

◆ unicoap_options_get()

◆ unicoap_options_get_next()

◆ unicoap_options_get_next_by_number()

◆ unicoap_options_get_next_query_by_name()

◆ unicoap_options_get_uint16()

◆ unicoap_options_get_uint24()

◆ unicoap_options_get_uint32()

◆ unicoap_options_get_uint8()

◆ unicoap_options_iterator_init()

◆ unicoap_options_remove()

◆ unicoap_options_remove_all()

◆ unicoap_options_set()

◆ unicoap_options_set_string()

◆ unicoap_options_set_uint()