CoAP options container. More...

Detailed Description

CoAP options container.

This structure provides a view into a storage buffer containing RFC7252-encoded options.

See also: Options

Definition at line 100 of file options.h.

#include <options.h>

Data Fields
size_t	storage_size
	Current size of encoded options.

size_t	storage_capacity
	Available capacity in options storage buffer.

unicoap_option_entry_t	entries [CONFIG_UNICOAP_OPTIONS_MAX]
	Helper array used to encode and decode options into options storage.

size_t	option_count
	Number of options present.

Essentials
static void	unicoap_options_init (unicoap_options_t options, uint8_t storage, size_t capacity)
	Initializes the given options structure.

static void	unicoap_options_clear (unicoap_options_t *options)
	Removes all options.

bool	unicoap_options_contains (const unicoap_options_t *options, unicoap_option_number_t number)
	Determines whether the given options container has one or more options with the given number.

Tools
static uint8_t *	unicoap_options_data (const unicoap_options_t *options)
	Retrieves storage buffer.

static size_t	unicoap_options_size (const unicoap_options_t *options)
	Retrieves total size of options in buffer.

ssize_t	unicoap_options_swap_storage (unicoap_options_t options, uint8_t destination, size_t capacity)
	Copies storage and adjusts `options` struct.

Non-repeatable options
Options that occur only once
static int	unicoap_options_remove (unicoap_options_t *options, unicoap_option_number_t number)
	Removes option with the given number, if present.

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.

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.

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.

Strings
static int	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.

static int	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.

Unsigned integers
static ssize_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.

static ssize_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.

static ssize_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.

static ssize_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.

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.

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.

Uri-Host
static ssize_t	unicoap_options_get_uri_host (const unicoap_options_t options, const char *host)
	Retrieves the `Uri-Host` option, if present.

static ssize_t	unicoap_options_set_uri_host (unicoap_options_t options, char host, size_t length)
	Sets the `Uri-Host` option.

static ssize_t	unicoap_options_set_uri_host_string (unicoap_options_t options, char host)
	Sets the `Uri-Host` option from null-terminated string.

static int	unicoap_options_remove_uri_host (unicoap_options_t *options)
	Removes the `Uri-Host` option, if present.

If-None-Match
static bool	unicoap_options_get_if_none_match (const unicoap_options_t *options)
	Determines whether the `If-None-Match` option is present.

static ssize_t	unicoap_options_set_if_none_match (unicoap_options_t *options, bool value)
	Sets the `If-None-Match` option.

Uri-Port
static ssize_t	unicoap_options_get_uri_port (const unicoap_options_t options, uint16_t port)
	Retrieves the `Uri-Port` option, if present.

static ssize_t	unicoap_options_set_uri_port (unicoap_options_t *options, uint16_t port)
	Sets the `Uri-Port` option.

static int	unicoap_options_remove_uri_port (unicoap_options_t *options)
	Removes the `Uri-Port` option, if present.

Content-Format
static ssize_t	unicoap_options_get_content_format (const unicoap_options_t options, unicoap_content_format_t format)
	Retrieves the `Content-Format` option, if present.

static ssize_t	unicoap_options_set_content_format (unicoap_options_t *options, unicoap_content_format_t format)
	Sets the `Content-Format` option.

static int	unicoap_options_remove_content_format (unicoap_options_t *options)
	Removes the `Content-Format` option, if present.

Max-Age
static ssize_t	unicoap_options_get_max_age (const unicoap_options_t options, uint32_t age)
	Retrieves the `Max-Age` option, if present.

static ssize_t	unicoap_options_set_max_age (unicoap_options_t *options, uint32_t age)
	Sets the `Max-Age` option.

static int	unicoap_options_remove_max_age (unicoap_options_t *options)
	Removes the `Max-Age` option, if present.

Accept
static ssize_t	unicoap_options_get_accept (const unicoap_options_t options, unicoap_content_format_t format)
	Retrieves the `Accept` option, if present.

static ssize_t	unicoap_options_set_accept (unicoap_options_t *options, unicoap_content_format_t format)
	Sets the `Accept` option.

static int	unicoap_options_remove_accept (unicoap_options_t *options)
	Removes the `Accept` option, if present.

Proxy-Scheme
static ssize_t	unicoap_options_get_proxy_scheme (const unicoap_options_t options, const char *scheme)
	Retrieves the `Proxy-Scheme` option, if present.

static ssize_t	unicoap_options_set_proxy_scheme (unicoap_options_t options, char scheme, size_t length)
	Sets the `Proxy-Scheme` option.

static ssize_t	unicoap_options_set_proxy_scheme_string (unicoap_options_t options, char scheme)
	Sets the `Proxy-Scheme` option from null-terminated string.

static int	unicoap_options_remove_proxy_scheme (unicoap_options_t *options)
	Removes the `Proxy-Scheme` option, if present.

Proxy-Uri
static ssize_t	unicoap_options_get_proxy_uri (const unicoap_options_t options, const char *uri)
	Retrieves the `Proxy-Uri` option, if present.

static ssize_t	unicoap_options_set_proxy_uri (unicoap_options_t options, char uri, size_t length)
	Sets the `Proxy-Uri` option.

static ssize_t	unicoap_options_set_proxy_uri_string (unicoap_options_t options, char uri)
	Sets the `Proxy-Uri` option from null-terminated string.

static int	unicoap_options_remove_proxy_uri (unicoap_options_t *options)
	Removes the `Proxy-Uri` option, if present.

No-Response
static ssize_t	unicoap_options_get_no_response (const unicoap_options_t options, uint8_t value)
	Retrieves the `No-Response` option, if present.

static ssize_t	unicoap_options_set_no_response (unicoap_options_t *options, uint8_t value)
	Sets the `No-Response` option.

static int	unicoap_options_remove_no_response (unicoap_options_t *options)
	Removes the `No-Response` option, if present.

If-Match
static ssize_t	unicoap_options_get_first_if_match (const unicoap_options_t options, const uint8_t *value)
	Retrieves the first `If-Match` option, if present.

static ssize_t	unicoap_options_get_next_if_match (unicoap_options_iterator_t iterator, const uint8_t *value)
	Gets the next `If-Match` option provided by the specified iterator.

static ssize_t	unicoap_options_add_if_match (unicoap_options_t options, uint8_t value, size_t size)
	Adds `If-Match` option.

static int	unicoap_options_remove_all_if_match (unicoap_options_t *options)
	Removes all `If-Match` options, if any.

ETag
static ssize_t	unicoap_options_get_first_etag (const unicoap_options_t options, const uint8_t *etag)
	Retrieves the first `ETag` option, if present.

static ssize_t	unicoap_options_get_next_etag (unicoap_options_iterator_t iterator, const uint8_t *etag)
	Gets the next `ETag` option provided by the specified iterator.

static ssize_t	unicoap_options_add_etag (unicoap_options_t options, uint8_t etag, size_t size)
	Adds `ETag` option.

static int	unicoap_options_remove_etags (unicoap_options_t *options)
	Removes all `ETag` options, if any.

Location-Path
static ssize_t	unicoap_options_get_first_location_path_component (const unicoap_options_t options, const char *component)
	Retrieves the first `Location-Path` option, if present.

static ssize_t	unicoap_options_get_next_location_path_component (unicoap_options_iterator_t iterator, const char *component)
	Gets the next `Location-Path` option provided by the specified iterator.

static ssize_t	unicoap_options_copy_location_path (const unicoap_options_t options, char path, size_t capacity)
	Copies absolute location path into the given buffer.

static ssize_t	unicoap_options_add_location_path_component (unicoap_options_t options, char component, size_t length)
	Adds `Location-Path` option.

static ssize_t	unicoap_options_add_location_path_component_string (unicoap_options_t options, char component)
	Adds `Location-Path` option from null-terminated string.

static ssize_t	unicoap_options_add_location_path (unicoap_options_t options, char path, size_t length)
	Adds multiple `Location-Path` options from string.

static ssize_t	unicoap_options_add_location_path_string (unicoap_options_t options, char path)
	Adds multiple `Location-Path` options from null-terminated string.

static int	unicoap_options_remove_location_path (unicoap_options_t *options)
	Removes all `Location-Path` options, if any.

Uri-Path
static ssize_t	unicoap_options_get_first_uri_path_component (const unicoap_options_t options, const char *component)
	Retrieves the first `Uri-Path` option, if present.

static ssize_t	unicoap_options_get_next_uri_path_component (unicoap_options_iterator_t iterator, const char *component)
	Gets the next `Uri-Path` option provided by the specified iterator.

static ssize_t	unicoap_options_copy_uri_path (const unicoap_options_t options, char path, size_t capacity)
	Copies absolute URI path into the given buffer.

static ssize_t	unicoap_options_add_uri_path_component (unicoap_options_t options, char component, size_t length)
	Adds `Uri-Path` option.

static ssize_t	unicoap_options_add_uri_path_component_string (unicoap_options_t options, char component)
	Adds `Uri-Path` option from null-terminated string.

static ssize_t	unicoap_options_add_uri_path (unicoap_options_t options, char path, size_t length)
	Adds multiple `Uri-Path` options from string.

static ssize_t	unicoap_options_add_uri_path_string (unicoap_options_t options, char path)
	Adds multiple `Uri-Path` options from null-terminated string.

static int	unicoap_options_remove_uri_path (unicoap_options_t *options)
	Removes all `Uri-Path` options, if any.

Uri-Query
static ssize_t	unicoap_options_get_first_uri_query (const unicoap_options_t options, const char *query)
	Retrieves the first `Uri-Query` option, if present.

static ssize_t	unicoap_options_get_next_uri_query (unicoap_options_iterator_t iterator, const char *query)
	Gets the next `Uri-Query` option provided by the specified iterator.

static ssize_t	unicoap_options_get_next_uri_query_by_name (unicoap_options_iterator_t iterator, const char name, const char **value)
	Gets the next `Uri-Query` option matching the given name, potentially skipping any options in between.

static ssize_t	unicoap_options_get_first_uri_query_by_name (unicoap_options_t options, const char name, const char **value)
	Retrieves the first `Uri-Query` option matching the given name, if present.

static ssize_t	unicoap_options_copy_uri_queries (const unicoap_options_t options, char queries, size_t capacity)
	Copies URI query string into the given buffer.

static ssize_t	unicoap_options_add_uri_query (unicoap_options_t options, char query, size_t length)
	Adds `Uri-Query` option.

static ssize_t	unicoap_options_add_uri_query_string (unicoap_options_t options, char query)
	Adds `Uri-Query` option from null-terminated string.

static ssize_t	unicoap_options_add_uri_queries (unicoap_options_t options, char queries, size_t length)
	Adds multiple `Uri-Query` options from string.

static ssize_t	unicoap_options_add_uri_queries_string (unicoap_options_t options, char queries)
	Adds multiple `Uri-Query` options from null-terminated string.

static int	unicoap_options_remove_uri_queries (unicoap_options_t *options)
	Removes all `Uri-Query` options, if any.

Location-Query
static ssize_t	unicoap_options_get_first_location_query (const unicoap_options_t options, const char *query)
	Retrieves the first `Location-Query` option, if present.

static ssize_t	unicoap_options_get_next_location_query (unicoap_options_iterator_t iterator, const char *query)
	Gets the next `Location-Query` option provided by the specified iterator.

static ssize_t	unicoap_options_get_next_location_query_by_name (unicoap_options_iterator_t iterator, const char name, const char **value)
	Gets the next `Location-Query` option matching the given name, potentially skipping any options in between.

static ssize_t	unicoap_options_get_first_location_query_by_name (unicoap_options_t options, const char name, const char **value)
	Retrieves the first `Location-Query` option matching the given name, if present.

static ssize_t	unicoap_options_copy_location_queries (const unicoap_options_t options, char queries, size_t capacity)
	Copies location query string into the given buffer.

static ssize_t	unicoap_options_add_location_query (unicoap_options_t options, char query, size_t length)
	Adds `Location-Query` option.

static ssize_t	unicoap_options_add_location_query_string (unicoap_options_t options, char query)
	Adds `Location-Query` option from null-terminated string.

static ssize_t	unicoap_options_add_location_queries (unicoap_options_t options, char queries, size_t length)
	Adds multiple `Location-Query` options from string.

static ssize_t	unicoap_options_add_location_queries_string (unicoap_options_t options, char queries)
	Adds multiple `Location-Query` options from null-terminated string.

static int	unicoap_options_remove_location_queries (unicoap_options_t *options)
	Removes all `Location-Query` options, if any.

Observe
static ssize_t	unicoap_options_get_observe (const unicoap_options_t options, uint32_t observe)
	Retrieves the `Observe` option, if present.

static ssize_t	unicoap_options_set_observe (unicoap_options_t *options, uint32_t observe)
	Sets the `Observe` option.

static int	unicoap_options_remove_observe (unicoap_options_t *options)
	Removes the `Observe` option, if present.

int	unicoap_options_set_observe_generated (unicoap_options_t *options)
	Sets the `Observe` option to a randomly generated value.

Block-wise Transfers
static ssize_t	unicoap_options_get_block (const unicoap_options_t options, unicoap_option_number_t number, unicoap_block_option_t block)
	Retrieves a `Block1` or `Block2` option.

static int	unicoap_options_set_block (unicoap_options_t *options, unicoap_option_number_t number, unicoap_block_option_t block)
	Sets the `Block1` or `Block2` option.

static ssize_t	unicoap_options_get_block1 (const unicoap_options_t options, unicoap_block_option_t block)
	Retrieves the `Block1` option, if present.

static ssize_t	unicoap_options_set_block1 (unicoap_options_t *options, unicoap_block_option_t block)
	Sets the `Block1` option.

static int	unicoap_options_remove_block1 (unicoap_options_t *options)
	Removes the `Block1` option, if present.

static ssize_t	unicoap_options_get_block2 (const unicoap_options_t options, unicoap_block_option_t block)
	Retrieves the `Block2` option, if present.

static ssize_t	unicoap_options_set_block2 (unicoap_options_t *options, unicoap_block_option_t block)
	Sets the `Block2` option.

static int	unicoap_options_remove_block2 (unicoap_options_t *options)
	Removes the `Block2` option, if present.

static ssize_t	unicoap_options_get_size1 (const unicoap_options_t options, uint32_t size)
	Retrieves the `Size1` option, if present.

static ssize_t	unicoap_options_set_size1 (unicoap_options_t *options, uint32_t size)
	Sets the `Size1` option.

static int	unicoap_options_remove_size1 (unicoap_options_t *options)
	Removes the `Size1` option, if present.

static ssize_t	unicoap_options_get_size2 (const unicoap_options_t options, uint32_t size)
	Retrieves the `Size2` option, if present.

static ssize_t	unicoap_options_set_size2 (unicoap_options_t *options, uint32_t size)
	Sets the `Size2` option.

static int	unicoap_options_remove_size2 (unicoap_options_t *options)
	Removes the `Size2` option, if present.

Repeatable options
Options that can occur more than once in a CoAP message
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.

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.

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.

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

Enumerating options
void	unicoap_options_dump_all (const unicoap_options_t *options)
	Iterates and dumps all options using `printf`

Field Documentation

◆ entries

unicoap_option_entry_t unicoap_options_t::entries[CONFIG_UNICOAP_OPTIONS_MAX]

Helper array used to encode and decode options into options storage.

Definition at line 121 of file options.h.

◆ option_count

size_t unicoap_options_t::option_count

Number of options present.

This is also the number of entries in the unicoap_options_t::entries array.

Definition at line 128 of file options.h.

◆ storage_capacity

size_t unicoap_options_t::storage_capacity

Available capacity in options storage buffer.

If capacity is insufficient, option accessor functions will return -ENOBUFS.

Definition at line 113 of file options.h.

◆ storage_size

size_t unicoap_options_t::storage_size

Current size of encoded options.

Definition at line 106 of file options.h.

The documentation for this struct was generated from the following file:

sys/include/net/unicoap/options.h

Detailed Description

Data Fields

Essentials

Tools

Non-repeatable options

Strings

Unsigned integers

Uri-Host

If-None-Match

Uri-Port

Content-Format

Max-Age

Accept

Proxy-Scheme

Proxy-Uri

No-Response

If-Match

ETag

Location-Path

Uri-Path

Uri-Query

Location-Query

Observe

Block-wise Transfers

Repeatable options

Enumerating options

Field Documentation

◆ entries

◆ option_count

◆ storage_capacity

◆ storage_size