- Generated on Thu Jul 24 2025 16:04:04 by
1.9.1
Access options from a CoAP message. More...
Access options from a CoAP message.
To allocate an options object, use UNICOAP_OPTIONS_ALLOC. Provide a name for the variable and an estimate for the total number of bytes needed to represent all options. If you are unsure, consider using UNICOAP_OPTIONS_ALLOC_DEFAULT.
After having allocated an options object, you can access individual options using the many accessor methods. Refer to Predefined Options for typed methods adjusted to each predefined option or Generic Option Methods for options where predefined methods are not provided.
Example:
Should you need to dump all options, use unicoap_options_t::unicoap_options_dump_all.
Modules | |
| Generic Option Methods | |
| Retrieve and manipulate generic repeatable and non-repeatable options in CoAP messages. | |
| Predefined Options | |
| Read, set, and add options predefined by IANA. | |
Files | |
| file | options.h |
| Options header. | |
Data Structures | |
| struct | unicoap_option_entry_t |
| Helper struct for options parser. More... | |
| struct | unicoap_options_t |
| CoAP options container. More... | |
Option characteristics | |
| static bool | unicoap_option_is_critical (unicoap_option_number_t option_number) |
| Determines whether the given option is considered critical. More... | |
| static bool | unicoap_option_is_safe_to_forward (unicoap_option_number_t option_number) |
| Determines whether the given option is safe to forward. More... | |
| static bool | unicoap_option_is_no_cache_key (unicoap_option_number_t option_number) |
| Determines whether the given option is not intended to be part of the cache key. More... | |
| static bool | unicoap_option_is_cache_key (unicoap_option_number_t option_number) |
| Determines whether the given option is intended to be part of the cache key. More... | |
Tools | |
| const char * | unicoap_string_from_option_number (unicoap_option_number_t number) |
| Returns label of option corresponding to the given number. More... | |
| ssize_t | unicoap_options_t::unicoap_options_swap_storage (unicoap_options_t *options, uint8_t *destination, size_t capacity) |
Copies storage and adjusts options struct. More... | |
| static uint8_t * | unicoap_options_t::unicoap_options_data (const unicoap_options_t *options) |
| Retrieves storage buffer. More... | |
| static size_t | unicoap_options_t::unicoap_options_size (const unicoap_options_t *options) |
| Retrieves total size of options in buffer. More... | |
Essentials | |
| static void | unicoap_options_t::unicoap_options_init (unicoap_options_t *options, uint8_t *storage, size_t capacity) |
| Initializes the given options structure. More... | |
| bool | unicoap_options_t::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. More... | |
| static void | unicoap_options_t::unicoap_options_clear (unicoap_options_t *options) |
| Removes all options. More... | |
Allocating option buffers | |
| #define | UNICOAP_OPTIONS_ALLOC(name, capacity) _UNICOAP_OPTIONS_ALLOC(_CONCAT3(name, _storage, __LINE__), name, capacity,) |
| Allocates options with buffer capacity. More... | |
| #define | UNICOAP_OPTIONS_ALLOC_STATIC(name, capacity) _UNICOAP_OPTIONS_ALLOC(_CONCAT3(name, _storage, __LINE__), name, capacity, static) |
| Statically allocates options with buffer capacity. More... | |
| #define | UNICOAP_OPTIONS_ALLOC_DEFAULT(name) UNICOAP_OPTIONS_ALLOC(name, CONFIG_UNICOAP_OPTIONS_BUFFER_DEFAULT_CAPACITY) |
| Allocates options with default capacity. More... | |
| #define | UNICOAP_OPTIONS_ALLOC_STATIC_DEFAULT(name) UNICOAP_OPTIONS_ALLOC_STATIC(name, CONFIG_UNICOAP_OPTIONS_BUFFER_DEFAULT_CAPACITY) |
| Statically allocates options with default capacity. More... | |
Auxiliary constants | |
| #define | EBADOPT 151 |
| Bad option. | |
| #define | EPAYLD 152 |
| Cannot read option, encountered payload marker. | |
| #define | UNICOAP_UINT24_MAX (0xffffff) |
| Largest number representable with 24 bits (3 bytes) | |
| #define | UNICOAP_UINT24_SIZE (3) |
| Size in bytes of number representable with 24 bits (3 bytes) | |
| #define | UNICOAP_UINT_MAX (14 + 255 + 0xffff) |
| Unsigned integer large enough to accommodate the maximum integer representable by CoAP option delta fields and extended length fields. More... | |
| #define UNICOAP_OPTIONS_ALLOC | ( | name, | |
| capacity | |||
| ) | _UNICOAP_OPTIONS_ALLOC(_CONCAT3(name, _storage, __LINE__), name, capacity,) |
Allocates options with buffer capacity.
| name | Name of the variable storing the options structure |
| capacity | Storage buffer capacity in bytes |
Allocates a new unicoap_options_t container and a storage buffer with the given capacity, and initializes it. No need to call unicoap_options_t::unicoap_options_init afterwards.
See UNICOAP_OPTIONS_ALLOC_STATIC for static allocation
| #define UNICOAP_OPTIONS_ALLOC_DEFAULT | ( | name | ) | UNICOAP_OPTIONS_ALLOC(name, CONFIG_UNICOAP_OPTIONS_BUFFER_DEFAULT_CAPACITY) |
Allocates options with default capacity.
| name | Name of the variable storing the options structure |
Allocates a new unicoap_options_t container and a storage buffer with CONFIG_UNICOAP_OPTIONS_BUFFER_DEFAULT_CAPACITY, and initializes it. No need to call unicoap_options_t::unicoap_options_init afterwards.
See UNICOAP_OPTIONS_ALLOC_STATIC_DEFAULT for static allocation
| #define UNICOAP_OPTIONS_ALLOC_STATIC | ( | name, | |
| capacity | |||
| ) | _UNICOAP_OPTIONS_ALLOC(_CONCAT3(name, _storage, __LINE__), name, capacity, static) |
Statically allocates options with buffer capacity.
| name | Name of the variable storing the options structure |
| capacity | Static storage buffer capacity in bytes |
Statically allocates a new unicoap_options_t container and a storage buffer with the given capacity, and initializes it. No need to call unicoap_options_t::unicoap_options_init afterwards.
See UNICOAP_OPTIONS_ALLOC for non-static allocation
| #define UNICOAP_OPTIONS_ALLOC_STATIC_DEFAULT | ( | name | ) | UNICOAP_OPTIONS_ALLOC_STATIC(name, CONFIG_UNICOAP_OPTIONS_BUFFER_DEFAULT_CAPACITY) |
Statically allocates options with default capacity.
| name | Name of the variable storing the options structure |
Statically allocates a new unicoap_options_t container and a storage buffer with CONFIG_UNICOAP_OPTIONS_BUFFER_DEFAULT_CAPACITY, and initializes it. No need to call unicoap_options_t::unicoap_options_init afterwards.
See UNICOAP_OPTIONS_ALLOC_DEFAULT for non-static allocation
| #define UNICOAP_UINT_MAX (14 + 255 + 0xffff) |
Unsigned integer large enough to accommodate the maximum integer representable by CoAP option delta fields and extended length fields.
CoAP option number.
These option numbers are not valid in signaling messages.
| Enumerator | |
|---|---|
| UNICOAP_OPTION_IF_MATCH |
|
| UNICOAP_OPTION_URI_HOST |
|
| UNICOAP_OPTION_ETAG |
|
| UNICOAP_OPTION_IF_NONE_MATCH |
|
| UNICOAP_OPTION_OBSERVE |
|
| UNICOAP_OPTION_URI_PORT |
|
| UNICOAP_OPTION_LOCATION_PATH |
|
| UNICOAP_OPTION_OSCORE | OSCORE option. Indicates that the CoAP message is an OSCORE message and that it contains a compressed COSE object.
|
| UNICOAP_OPTION_URI_PATH |
|
| UNICOAP_OPTION_CONTENT_FORMAT |
|
| UNICOAP_OPTION_MAX_AGE |
|
| UNICOAP_OPTION_URI_QUERY |
Examples: |
| UNICOAP_OPTION_HOP_LIMIT |
Used to prevent infinite loops when communicating over multiple proxies.
|
| UNICOAP_OPTION_ACCEPT |
|
| UNICOAP_OPTION_Q_BLOCK1 |
Used for block-wise transfer supporting robust transmission in requests.
|
| UNICOAP_OPTION_LOCATION_QUERY |
|
| UNICOAP_OPTION_EDHOC | EDHOC option. Used in a CoAP request to signal that the request payload conveys both an EDHOC message_3 and OSCORE protected data, combined together.
|
| UNICOAP_OPTION_BLOCK2 |
Used to indicate the block size and number in a block-wise transfer. Used only to transfer a request body.
|
| UNICOAP_OPTION_BLOCK1 |
Used to indicate the block size and number in a block-wise transfer. Used only to transfer a response body.
|
| UNICOAP_OPTION_SIZE2 | Size2 option. Used by clients to request an estimate of a resource's total size from a server during block-wise transfer and by servers to inform clients about the size. |
| UNICOAP_OPTION_Q_BLOCK2 | Q-Block2 option. Used for block-wise transfer supporting robust transmission in responses.
|
| UNICOAP_OPTION_PROXY_URI |
|
| UNICOAP_OPTION_PROXY_SCHEME |
|
| UNICOAP_OPTION_SIZE1 | Size1 option. Used by clients to give servers an estimate of the total request payload size during block-wise server and by servers to indicate the maximum acceptable payload size in a 4.13 = "Request Entity Too Large") response. |
| UNICOAP_OPTION_ECHO | Echo option. Enables a CoAP server to verify the freshness of a request or to force a client to demonstrate reachability at its claimed network address.
|
| UNICOAP_OPTION_NO_RESPONSE | suppress CoAP response
|
| UNICOAP_OPTION_REQUEST_TAG | Request-Tag option. Allows a CoAP server to match block-wise message fragments belonging to the same request.
|
| UNICOAP_SIGNALING_CSM_OPTION_MAX_MESSAGE_SIZE | Max-Message-Size option Applies to
|
| UNICOAP_SIGNALING_CSM_OPTION_BLOCKWISE_TRANSFER | Blockwise-Transfer option Applies to
|
| UNICOAP_SIGNALING_PING_PONG_OPTION_CUSTODY | Custody option Applies to
|
| UNICOAP_SIGNALING_RELEASE_OPTION_ALTERNATIVE_ADDRESS | Alternative-Address option Applies to
|
| UNICOAP_SIGNALING_RELEASE_OPTION_HOLD_OFF | Hold-Off option Applies to
|
| UNICOAP_SIGNALING_ABORT_OPTION_BAD_CSM | Bad-CSM-Option option Applies to
|
Definition at line 419 of file constants.h.
|
inlinestatic |
Determines whether the given option is intended to be part of the cache key.
Whether an option is considered a NoCacheKey is independent from the option's value.
| option_number | The option number |
|
inlinestatic |
Determines whether the given option is considered critical.
Criticality is independent from the corresponding option's value. As per CoAP RFC 7252, critical options must never be silently ignored.
| option_number | The option number |
|
inlinestatic |
Determines whether the given option is not intended to be part of the cache key.
Whether an option is considered NoCacheKey is independent from the option's value.
| option_number | The option number |
|
inlinestatic |
Determines whether the given option is safe to forward.
Whether an option is safe to forward is independent from the corresponding option's value.
| option_number | The option number |
|
inline |
| 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.
| [in] | options | Options |
| number | The option number |
true if options contains an options with the given number
|
inline |
|
inline |
|
inline |
| ssize_t unicoap_options_swap_storage | ( | unicoap_options_t * | options, |
| uint8_t * | destination, | ||
| size_t | capacity | ||
| ) |
Copies storage and adjusts options struct.
| [in,out] | options | Options struct whose storage to swap |
| [in,out] | destination | New storage buffer |
| capacity | destination capacity |
| <tt>0</tt> | on success |
| <tt>-ENOBUFS</tt> | destination is not sufficiently big |
| const char* unicoap_string_from_option_number | ( | unicoap_option_number_t | number | ) |
Returns label of option corresponding to the given number.
| number | Option number |
Content-Format 1.9.1