/* * Copyright (C) 2024-2025 Carl Seifert * Copyright (C) 2024-2025 TU Dresden * * This file is subject to the terms and conditions of the GNU Lesser General * Public License v2.1. See the file LICENSE in the top level directory for * more details. */ #pragma once #include #include #include #include #include #include #include "byteorder.h" #include "net/unicoap/constants.h" #include "net/unicoap/util_macros.h" /** * @defgroup net_unicoap_options Options * @ingroup net_unicoap_message * @brief Access options from a CoAP message * @{ * * To allocate an options object, use @ref 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 @ref UNICOAP_OPTIONS_ALLOC_DEFAULT. * * After having allocated an options object, you can access individual options using the many * accessor methods. Refer to @ref net_unicoap_options_predefined for typed methods adjusted to * each predefined option or @ref net_unicoap_options_generic for options where predefined methods * are not provided. * * **Example**: * ```c * UNICOAP_OPTIONS_ALLOC(my_options, 20); * * int res = 0; * if ((res = unicoap_options_add_uri_queries_string(&my_options, "a=1&b=2")) < 0) { * printf("error: could not add Uri-Query options: %i (%s)\n", res, strerror(-res)); * } * * if (unicoap_options_set_accept(&my_options, UNICOAP_FORMAT_TEXT) < 0) { * printf("error: could set Accept option: %i (%s)\n", res, strerror(-res)); * } * ``` * * Should you need to dump all options, use @ref unicoap_options_t::unicoap_options_dump_all. */ /** * @file * @brief Options header * @author Carl Seifert */ #ifdef __cplusplus extern "C" { #endif /* MARK: - Essentials */ /** * @name Essentials * @{ */ /** * @brief Helper struct for options parser */ typedef struct { /** * @brief Pointer into options storage where this option starts. * @note This is not the start of the given option's value. */ uint8_t* data; /** * @brief Number of bytes this option is comprised of */ uint16_t size; /** * @brief Option number */ unicoap_option_number_t number; } unicoap_option_entry_t; /** * @brief CoAP options container * * This structure provides a *view* into a storage buffer * containing [RFC7252](https://datatracker.ietf.org/doc/html/rfc7252)-encoded options. * * @see @ref net_unicoap_options */ typedef struct { /* TODO: OSCORE: read-only due to options stored in two different buffers */ /** * @brief Current size of encoded options */ size_t storage_size; /** * @brief Available capacity in options storage buffer * * If capacity is insufficient, option accessor functions will return `-ENOBUFS`. */ size_t storage_capacity; /** * @brief Helper array used to encode and decode options into options storage. * @internal * * @see @ref CONFIG_UNICOAP_OPTIONS_MAX */ unicoap_option_entry_t entries[CONFIG_UNICOAP_OPTIONS_MAX]; /** * @brief Number of options present * * This is also the number of entries in the @ref unicoap_options_t::entries array. */ size_t option_count; } unicoap_options_t; /** * @brief Initializes the given options structure. * @memberof unicoap_options_t * * @param[in,out] options Options struct to initialize * @param[in] storage A buffer unicoap will use to store option values in * @param capacity The number of usable bytes in @p storage */ static inline void unicoap_options_init(unicoap_options_t* options, uint8_t* storage, size_t capacity) { options->entries->data = storage; options->option_count = 0; options->storage_size = 0; options->storage_capacity = capacity; } /** * @brief Determines whether the given options container has one or more options with the given * number. * * @memberof unicoap_options_t * * @param[in] options Options * @param number The option number * * @returns `true` if @p options contains an options with the given number */ bool unicoap_options_contains(const unicoap_options_t* options, unicoap_option_number_t number); /** * @brief Removes all options * @memberof unicoap_options_t * * @param[in,out] options Options */ static inline void unicoap_options_clear(unicoap_options_t* options) { options->option_count = 0; options->storage_size = 0; } /** @} */ /* MARK: - Allocating option buffers */ /** * @name Allocating option buffers * @{ */ #ifndef DOXYGEN # define _UNICOAP_OPTIONS_ALLOC(_buf, _name, capacity, _static) \ _static uint8_t _buf[capacity]; \ _static unicoap_options_t _name = { \ .entries = { { .data = _buf } }, \ .storage_capacity = capacity, \ }; #endif /** * @brief Allocates options with buffer capacity * * @param name Name of the variable storing the options structure * @param capacity Storage buffer capacity in bytes * * Allocates a new @ref unicoap_options_t container and a storage buffer with * the given capacity, and initializes it. No need to call * @ref unicoap_options_t::unicoap_options_init afterwards. * * See @ref UNICOAP_OPTIONS_ALLOC_STATIC for static allocation */ #define UNICOAP_OPTIONS_ALLOC(name, capacity) \ _UNICOAP_OPTIONS_ALLOC(_CONCAT3(name, _storage, __LINE__), name, capacity,) /** * @brief Statically allocates options with buffer capacity * * @param name Name of the variable storing the options structure * @param capacity Static storage buffer capacity in bytes * * Statically allocates a new @ref unicoap_options_t container and a storage * buffer with the given capacity, and initializes it. No need to call * @ref unicoap_options_t::unicoap_options_init afterwards. * * See @ref UNICOAP_OPTIONS_ALLOC for non-static allocation */ #define UNICOAP_OPTIONS_ALLOC_STATIC(name, capacity) \ _UNICOAP_OPTIONS_ALLOC(_CONCAT3(name, _storage, __LINE__), name, capacity, static) /** * @brief Allocates options with default capacity * * @param name Name of the variable storing the options structure * * Allocates a new @ref unicoap_options_t container and a storage buffer with * @ref CONFIG_UNICOAP_OPTIONS_BUFFER_DEFAULT_CAPACITY, and initializes it. * No need to call @ref unicoap_options_t::unicoap_options_init afterwards. * * See @ref UNICOAP_OPTIONS_ALLOC_STATIC_DEFAULT for static allocation */ #define UNICOAP_OPTIONS_ALLOC_DEFAULT(name) \ UNICOAP_OPTIONS_ALLOC(name, CONFIG_UNICOAP_OPTIONS_BUFFER_DEFAULT_CAPACITY) /** * @brief Statically allocates options with default capacity * * @param name Name of the variable storing the options structure * * Statically allocates a new @ref unicoap_options_t container and a storage buffer * with @ref CONFIG_UNICOAP_OPTIONS_BUFFER_DEFAULT_CAPACITY, and initializes it. * No need to call @ref unicoap_options_t::unicoap_options_init afterwards. * * See @ref UNICOAP_OPTIONS_ALLOC_DEFAULT for non-static allocation */ #define UNICOAP_OPTIONS_ALLOC_STATIC_DEFAULT(name) \ UNICOAP_OPTIONS_ALLOC_STATIC(name, CONFIG_UNICOAP_OPTIONS_BUFFER_DEFAULT_CAPACITY) /** @} */ /* MARK: - Option characteristics */ /** * @name Option characteristics * @{ */ /** * @brief Determines whether the given option is considered critical * * Criticality is independent from the corresponding option's value. * As per [CoAP RFC 7252](https://datatracker.ietf.org/doc/html/rfc7252), * critical options must never be silently ignored. * * @param option_number The option number * @returns A boolean value indicating whether options with the given number are critical */ static inline bool unicoap_option_is_critical(unicoap_option_number_t option_number) { return option_number & 1; } /** * @brief Determines whether the given option is safe to forward * * Whether an option is safe to forward is independent from the corresponding option's value. * * @param option_number The option number * @returns A boolean value indicating whether options with the given number are safe to forward */ static inline bool unicoap_option_is_safe_to_forward(unicoap_option_number_t option_number) { return (option_number & 2) == 0; } /** * @brief Determines whether the given option is **not** intended to be part of the cache key * * Whether an option is considered * [NoCacheKey](https://datatracker.ietf.org/doc/html/rfc7252#section-5.4.2) * is independent from the option's value. * * @param option_number The option number * @returns A boolean value indicating whether options with the given number are **not** a cache key */ static inline bool unicoap_option_is_no_cache_key(unicoap_option_number_t option_number) { return ((option_number & 0x1e) == 0x1c); } /** * @brief Determines whether the given option is intended to be part of the cache key * * Whether an option is considered a * [NoCacheKey](https://datatracker.ietf.org/doc/html/rfc7252#section-5.4.2) * is independent from the option's value. * * @param option_number The option number * @returns A boolean value indicating whether options with the given number are a cache key */ static inline bool unicoap_option_is_cache_key(unicoap_option_number_t option_number) { return ((option_number & 0x1e) != 0x1c); } /** @} */ /* MARK: - Tools */ /** * @name Tools * @{ */ /** * @brief Returns label of option corresponding to the given number * @param number Option number * @returns Null-terminated string label, such as `Content-Format` */ const char* unicoap_string_from_option_number(unicoap_option_number_t number); /** * @brief Copies storage and adjusts @p options struct. * @memberof unicoap_options_t * * @param[in,out] options Options struct whose storage to swap * @param[in,out] destination New storage buffer * @param capacity @p destination capacity * * @returns negative number on error * @retval `0` on success * @retval `-ENOBUFS` @p destination is not sufficiently big */ ssize_t unicoap_options_swap_storage(unicoap_options_t* options, uint8_t* destination, size_t capacity); /** * @brief Retrieves storage buffer * @memberof unicoap_options_t * * @param[in] options Options * @returns Pointer to first byte of storage buffer, can be `NULL` */ static inline uint8_t* unicoap_options_data(const unicoap_options_t* options) { return options->entries->data; } /** * @brief Retrieves total size of options in buffer * @memberof unicoap_options_t * * @param[in] options Options * @returns Size of options in buffer in bytes */ static inline size_t unicoap_options_size(const unicoap_options_t* options) { return options->storage_size; } /** @} */ /* MARK: - Auxiliary constants */ /** * @name Auxiliary constants * @{ */ /** @brief Bad option */ #if !defined(EBADOPT) || defined(DOXYGEN) # define EBADOPT 151 #endif /** @brief Cannot read option, encountered payload marker */ #if !defined(EPAYLD) || defined(DOXYGEN) # define EPAYLD 152 #endif /** @brief Largest number representable with 24 bits (3 bytes) */ #define UNICOAP_UINT24_MAX (0xffffff) /** @brief Size in bytes of number representable with 24 bits (3 bytes) */ #define UNICOAP_UINT24_SIZE (3) /** * @brief Unsigned integer large enough to accommodate the maximum integer * representable by CoAP option delta fields and extended length fields. * * @see [CoAP RFC 7252, 3.1](https://datatracker.ietf.org/doc/html/rfc7252#section-3.1) */ #define UNICOAP_UINT_MAX (14 + 255 + 0xffff) /** @} */ /* MARK: - Generic Option Methods - */ /** * @defgroup net_unicoap_options_generic Generic Option Methods * @ingroup net_unicoap_options * @brief Retrieve and manipulate generic repeatable and non-repeatable options in CoAP messages * @{ */ /* MARK: - Repeatable options */ /** * @name Repeatable options * @{ * Options that can occur more than once in a CoAP message */ /** * @brief Adds a repeatable option with the given value. * @memberof unicoap_options_t * * Use this function to insert multiple options with the same number but potentially different * values. * * @param[in] options Options * @param number Option number * @param[in] value Option value to set * @param value_size Number of bytes the @p value is made up of * * @returns Negative integer on error * @retval Zero on success * @retval `-ENOBUFS` if options buffer lacks sufficient capacity to add option */ int unicoap_options_add(unicoap_options_t* options, unicoap_option_number_t number, const uint8_t* value, size_t value_size); /** * @brief Splits the given value into separate values and adds them as option values * @memberof unicoap_options_t * * Use this function to insert multiple options with the same number but potentially different * values. * The @p buffer will be sliced everywhere the @p separator occurs. This is the same as calling * @ref unicoap_options_add for each chunk inbeetween separator bytes. * * @param[in] options Options * @param number Option number * @param[in] buffer Option values separated by @p separator * @param size Number of bytes the value is made up of * @param separator Separator byte used to indicate boundaries between option values * * @returns Negative integer on error or zero on success * @retval `-ENOBUFS` if options buffer lacks sufficient capacity to add options * * @note A leading @p separator in @p buffer will be ignored by this function. */ 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); /** * @brief Copies the values of all options with the given number joined by the given separator * @memberof unicoap_options_t * * Use this API with repeatable options * * @param[in] options Options * @param number Option number * @param[in,out] buffer Buffer to copy string value into, must be large enough to carry characters. * @param capacity Number of usable bytes in @p dest * @param separator Separator to insert between option values. * * @returns Size of generated byte sequence, including separators or negative integer on error * @retval `-ENOBUFS` if @p buffer lacks sufficient capacity to store string * * @pre @p capacity is greater than zero. * * @warning This function does _not_ create a null-terminated C string. */ 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); /** * @brief Removes all options with the given number, if any * @memberof unicoap_options_t * * Use this API with repeatable options * * @param[in,out] options Options * @param 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 */ int unicoap_options_remove_all(unicoap_options_t* options, unicoap_option_number_t number); /** @} */ /* MARK: - Non-repeatable options */ /** * @name Non-repeatable options * @{ * Options that occur only once */ /** * @brief Retrieves the value of the option with given value, if present * @memberof unicoap_options_t * * @param[in] options Options * @param number Option number * @param[in,out] value Option value. Provide a pointer to a an `uint8_t` pointer, which may be * `NULL`. * * @return Size of option value (zero or more bytes) or negative errno if the get operation failed * @retval `-ENOENT` Options not found * @retval `-EBADOPT` Options buffer is corrupted */ ssize_t unicoap_options_get(const unicoap_options_t* options, unicoap_option_number_t number, const uint8_t** value); /** * @brief Copies the value of the option with given value, if present, into a buffer * @memberof unicoap_options_t * * @param[in] options Options * @param number Option number * @param[in,out] dest Destination buffer where option value will be copied into * @param capacity Number of usable bytes in the @p dest buffer * * @return Size of option value (zero or more bytes) or negative errno if the get operation failed * @retval `-ENOENT` Options not found * @retval `-EBADOPT` Options buffer is corrupted * @retval `-ENOBUFS` if @p dest lacks sufficient capacity to store value */ ssize_t unicoap_options_copy_value(const unicoap_options_t* options, unicoap_option_number_t number, uint8_t* dest, size_t capacity); /** * @brief Sets the option with the given number * @memberof unicoap_options_t * * @param[in,out] options Options * @param number Option number * @param[in] value Option value * @param value_size Number of bytes the @p value is made up of * * @returns Zero on success or egative integer on error instead * @retval `-ENOBUFS` if options storage buffer lacks sufficient capacity to set option */ int unicoap_options_set(unicoap_options_t* options, unicoap_option_number_t number, const uint8_t* value, size_t value_size); /** * @brief Removes option with the given number, if present * @memberof unicoap_options_t * * @param options Options * @param 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 */ static inline int unicoap_options_remove(unicoap_options_t* options, unicoap_option_number_t number) { /* reuse unicoap_options_remove_all, helps decrease binary size */ return unicoap_options_remove_all(options, number); } /** @} */ /* MARK: - Enumerating options */ /** * @name Enumerating options * @{ */ /** * @brief The iterator you use to retrieve option values in-order. * * ## Example * ```c * unicoap_option_iterator iterator = {0}; * unicoap_options_iterator_init(&iterator, message->options); * * uint8_t* value = NULL; * ssize_t size = -1; * unicoap_option_number_t number = 0; * * while ((size = unicoap_options_get_next(&iterator, &number, &value)) >= 0) { * printf("%s (%i) = (%" PRIiSIZE " bytes): ", unicoap_string_from_option_number(number), number, size); * my_dump_hex(value, size); * } * ``` */ typedef struct { /** * @brief Options */ unicoap_options_t* options; /** * @brief Current option's index */ size_t index; } unicoap_options_iterator_t; /** * @brief Initializes the given iterator structure * @memberof unicoap_options_iterator_t * * @param[in,out] iterator Option iterator struct to initialize * @param[in] options Options to iterate over */ static inline void unicoap_options_iterator_init(unicoap_options_iterator_t* iterator, unicoap_options_t* options) { assert(iterator); assert(options); assert(options->entries->data); iterator->options = options; iterator->index = 0; } /** * @brief Gets the next option provided by the given iterator * @memberof unicoap_options_iterator_t * * This is a zero-copy API. * * @param[in,out] iterator Option iterator * @param[out] number The number of the next option * @param[out] value A pointer to next option's value * * @returns Positive size of option value on success or negative integer on error instead * @retval `-1` if the iterator is finished * @retval `-EBADOPT` Options buffer is corrupted */ ssize_t unicoap_options_get_next(unicoap_options_iterator_t* iterator, unicoap_option_number_t* number, const uint8_t** value); /** * @brief Gets the next option with the given number, potentially skipping any options in between. * @memberof unicoap_options_iterator_t * * This is a zero-copy API. Use this function to iterate over specific options that may occur more * than once. * * @param[in,out] iterator Option iterator * @param number The option number to look out for * @param[out] value A pointer to next option's value * * @returns Positive size of option value or negative integer on error * @retval `-1` if the iterator is finished * @retval `-EBADOPT` Options buffer is corrupted */ ssize_t unicoap_options_get_next_by_number(unicoap_options_iterator_t* iterator, unicoap_option_number_t number, const uint8_t** value); /** * @brief Gets the next query option matching the given name, potentially skipping any options * in between. * * @memberof unicoap_options_iterator_t * * 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`. * * @param[in,out] iterator Option iterator * @param[out] number Option number * @param[in] name Name of UTF-8 query parameter to find * @param[out] value Pointer to a UTF-8 string variable * * @returns Positive size of option value or Negative integer on error * @retval `-EBADOPT` Option is corrupted * @retval `-1` if the iterator is finished * * @warning @p 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](https://datatracker.ietf.org/doc/html/rfc7252#section-3.2) */ 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); /** * @brief Iterates and dumps all options using `printf` * @memberof unicoap_options_t * * @param[in] options Options */ void unicoap_options_dump_all(const unicoap_options_t* options); /** @} */ /* MARK: - Strings */ /** * @name Strings * @{ */ /** * @brief Sets a non-repeatable option to the given string value. * @memberof unicoap_options_t * * @param[in] options Options * @param number Option number * @param[in] string String option value to set * @param 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 * @retval `-ENOBUFS` if options buffer lacks sufficient capacity to set option */ static inline int unicoap_options_set_string(unicoap_options_t* options, unicoap_option_number_t number, const char* string, size_t count) { return unicoap_options_set(options, number, (uint8_t*)string, ((count > 0) && string) ? count : strlen(string)); } /** * @brief Adds a repeatable option with the given string value. * @memberof unicoap_options_t * * Use this function to insert multiple options with the same number but potentially different * values. * * @param[in] options Options * @param number Option number * @param[in] string String option value to set * @param 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 * @retval `-ENOBUFS` if options buffer lacks sufficient capacity to add option */ static inline int unicoap_options_add_string(unicoap_options_t* options, unicoap_option_number_t number, const char* string, size_t count) { return unicoap_options_add(options, number, (uint8_t*)string, ((count > 0) && string) ? count : strlen(string)); } /** @} */ /* MARK: - Unsigned integers */ /** * @name Unsigned integers * @{ */ #ifndef DOXYGEN /** * @brief Retrieves an unsigned option value with a configurable maximum width * @memberof unicoap_options_t * * @param[in] options Options * @param number Option number * @param[in,out] uint Pointer to 32-bit integer that will store unsigned integer in host byte order * @param max_size Maximum number of bytes used to represent the integer (1 to 4) * * @returns Number of bytes occupied by the unsigned integer in the option value or negative * integer on error * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option is corrupted or integer wider than expected * * @pre @p max_size does not exceed `sizeof(uint32_t)` */ ssize_t _unicoap_options_get_variable_uint(const unicoap_options_t* options, unicoap_option_number_t number, uint32_t* uint, size_t max_size); #endif /** * @brief Retrieves an unsigned option value that takes up at most 4 bytes. * @memberof unicoap_options_t * * 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. * * @param[in] options Options * @param number Option number * @param[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 * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option is corrupted */ static inline ssize_t unicoap_options_get_uint32(const unicoap_options_t* options, unicoap_option_number_t number, uint32_t* uint) { return _unicoap_options_get_variable_uint(options, number, uint, sizeof(uint32_t)); } /** * @brief Retrieves an unsigned option value that takes up at most 3 bytes. * @memberof unicoap_options_t * * 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. * * @param[in] options Options * @param number Option number * @param[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 * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option is corrupted */ static inline ssize_t unicoap_options_get_uint24(const unicoap_options_t* options, unicoap_option_number_t number, uint32_t* uint) { return _unicoap_options_get_variable_uint(options, number, uint, UNICOAP_UINT24_SIZE); } /** * @brief Retrieves an unsigned option value that takes up at most 2 bytes. * @memberof unicoap_options_t * * 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. * * @param[in] options Options * @param number Option number * @param[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 * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option is corrupted */ static inline ssize_t unicoap_options_get_uint16(const unicoap_options_t* options, unicoap_option_number_t number, uint16_t* uint) { uint32_t _uint = 0; int res = _unicoap_options_get_variable_uint(options, number, &_uint, sizeof(uint16_t)); *uint = (uint16_t)_uint; return res; } /** * @brief Retrieves an unsigned option value that takes up at most one bytes. * @memberof unicoap_options_t * * 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. * * @param[in] options Options * @param number Option number * @param[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 * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option is corrupted * @retval `-ENOBUFS` Option value was bigger than 1 byte */ static inline ssize_t unicoap_options_get_uint8(const unicoap_options_t* options, unicoap_option_number_t number, uint8_t* uint) { return unicoap_options_copy_value(options, number, uint, sizeof(uint8_t)); } /** * @brief Sets the option with the given number to the unsigned integer value passed. * @memberof unicoap_options_t * * 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. * * @param[in] options Options * @param number Option number * @param value Unsigned integer option value * * @returns Zero on success or negative integer on error * @retval `-ENOBUFS` if options buffer lacks sufficient capacity to set option */ int unicoap_options_set_uint(unicoap_options_t* options, unicoap_option_number_t number, uint32_t value); /** * @brief Adds a repeatable option with the given unsigned integer value. * @memberof unicoap_options_t * * 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. * * @param[in] options Options * @param number Option number * @param value Unsigned integer option value * * @returns Zero on success or negative integer on error * @retval `-ENOBUFS` if options buffer lacks sufficient capacity to add option */ int unicoap_options_add_uint(unicoap_options_t* options, unicoap_option_number_t number, uint32_t value); /** @} */ /** @} */ /* MARK: - Predefined Options - */ /** * @defgroup net_unicoap_options_predefined Predefined Options * @ingroup net_unicoap_options * @brief Read, set, and add options predefined by IANA * @{ */ /* MARK: - Uri-Host */ /** * @name Uri-Host * @{ */ /** * @brief Retrieves the `Uri-Host` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] host Pointer to value variable as buffer of UTF-8 code units * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_uri_host(const unicoap_options_t* options, const char** host) { return unicoap_options_get(options, UNICOAP_OPTION_URI_HOST, (const uint8_t**)host); } /** * @brief Sets the `Uri-Host` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] host `Uri-Host` value as buffer of UTF-8 code units * @param length Number of UTF-8 code units in @p host, excluding null-terminator * (if present) in bytes * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option * * @pre @p host must be at least of size 1 bytes * @pre @p host size must not exceed 255 bytes */ static inline ssize_t unicoap_options_set_uri_host(unicoap_options_t* options, char* host, size_t length) { assert(length > 0 && length <= 255); return unicoap_options_set(options, UNICOAP_OPTION_URI_HOST, (uint8_t*)host, length); } /** * @brief Sets the `Uri-Host` option from null-terminated string * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] host `Uri-Host` value as buffer of UTF-8 code units, must be null-terminated * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option * * @pre @p host must be at least of size 1 bytes * @pre @p host size must not exceed 255 bytes * * Uses `strlen` to calculate the number of code units. * @see @ref unicoap_options_set_uri_host */ static inline ssize_t unicoap_options_set_uri_host_string(unicoap_options_t* options, char* host) { return unicoap_options_set_uri_host(options, host, strlen(host)); } /** * @brief Removes the `Uri-Host` option, if present * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_uri_host(unicoap_options_t* options) { return unicoap_options_remove(options, UNICOAP_OPTION_URI_HOST); } /** @} */ /* Uri-Host */ /* MARK: - If-None-Match */ /** * @name If-None-Match * @{ */ /** * @brief Determines whether the `If-None-Match` option is present * @memberof unicoap_options_t * * @param[in] options Options to read from * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline bool unicoap_options_get_if_none_match(const unicoap_options_t* options) { return unicoap_options_contains(options, UNICOAP_OPTION_IF_NONE_MATCH); } /** * @brief Sets the `If-None-Match` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param value `If-None-Match` value * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option */ static inline ssize_t unicoap_options_set_if_none_match(unicoap_options_t* options, bool value) { if (value) { return unicoap_options_remove(options, UNICOAP_OPTION_IF_NONE_MATCH); } else { return unicoap_options_set(options, UNICOAP_OPTION_IF_NONE_MATCH, NULL, 0); } } /** @} */ /* If-None-Match */ /* MARK: - Uri-Port */ /** * @name Uri-Port * @{ */ /** * @brief Retrieves the `Uri-Port` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] port Pointer to value variable * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_uri_port(const unicoap_options_t* options, uint16_t* port) { return unicoap_options_get_uint16(options, UNICOAP_OPTION_URI_PORT, port); } /** * @brief Sets the `Uri-Port` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param port `Uri-Port` value * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option */ static inline ssize_t unicoap_options_set_uri_port(unicoap_options_t* options, uint16_t port) { return unicoap_options_set_uint(options, UNICOAP_OPTION_URI_PORT, (uint32_t)port); } /** * @brief Removes the `Uri-Port` option, if present * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_uri_port(unicoap_options_t* options) { return unicoap_options_remove(options, UNICOAP_OPTION_URI_PORT); } /** @} */ /* Uri-Port */ /* MARK: - Content-Format */ /** * @name Content-Format * @{ */ /** * @brief Retrieves the `Content-Format` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] format Pointer to value variable * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_content_format(const unicoap_options_t* options, unicoap_content_format_t* format) { return unicoap_options_get_uint16(options, UNICOAP_OPTION_CONTENT_FORMAT, (uint16_t*)format); } /** * @brief Sets the `Content-Format` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param format `Content-Format` value * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option */ static inline ssize_t unicoap_options_set_content_format(unicoap_options_t* options, unicoap_content_format_t format) { return unicoap_options_set_uint(options, UNICOAP_OPTION_CONTENT_FORMAT, (uint32_t)format); } /** * @brief Removes the `Content-Format` option, if present * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_content_format(unicoap_options_t* options) { return unicoap_options_remove(options, UNICOAP_OPTION_CONTENT_FORMAT); } /** @} */ /* Content-Format */ /* MARK: - Max-Age */ /** * @name Max-Age * @{ */ /** * @brief Retrieves the `Max-Age` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] age Pointer to value variable * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_max_age(const unicoap_options_t* options, uint32_t* age) { return unicoap_options_get_uint32(options, UNICOAP_OPTION_MAX_AGE, age); } /** * @brief Sets the `Max-Age` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param age `Max-Age` value * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option */ static inline ssize_t unicoap_options_set_max_age(unicoap_options_t* options, uint32_t age) { return unicoap_options_set_uint(options, UNICOAP_OPTION_MAX_AGE, age); } /** * @brief Removes the `Max-Age` option, if present * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_max_age(unicoap_options_t* options) { return unicoap_options_remove(options, UNICOAP_OPTION_MAX_AGE); } /** @} */ /* Max-Age */ /* MARK: - Accept */ /** * @name Accept * @{ */ /** * @brief Retrieves the `Accept` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] format Pointer to value variable * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_accept(const unicoap_options_t* options, unicoap_content_format_t* format) { return unicoap_options_get_uint16(options, UNICOAP_OPTION_ACCEPT, (uint16_t*)format); } /** * @brief Sets the `Accept` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param format `Accept` value * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option */ static inline ssize_t unicoap_options_set_accept(unicoap_options_t* options, unicoap_content_format_t format) { return unicoap_options_set_uint(options, UNICOAP_OPTION_ACCEPT, (uint32_t)format); } /** * @brief Removes the `Accept` option, if present * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_accept(unicoap_options_t* options) { return unicoap_options_remove(options, UNICOAP_OPTION_ACCEPT); } /** @} */ /* Accept */ /* MARK: - Proxy-Scheme */ /** * @name Proxy-Scheme * @{ */ /** * @brief Retrieves the `Proxy-Scheme` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] scheme Pointer to value variable as buffer of UTF-8 code units * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_proxy_scheme(const unicoap_options_t* options, const char** scheme) { return unicoap_options_get(options, UNICOAP_OPTION_PROXY_SCHEME, (const uint8_t**)scheme); } /** * @brief Sets the `Proxy-Scheme` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] scheme `Proxy-Scheme` value as buffer of UTF-8 code units * @param length Number of UTF-8 code units in @p scheme, excluding null-terminator * (if present) in bytes * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option * */ static inline ssize_t unicoap_options_set_proxy_scheme(unicoap_options_t* options, char* scheme, size_t length) { return unicoap_options_set(options, UNICOAP_OPTION_PROXY_SCHEME, (uint8_t*)scheme, length); } /** * @brief Sets the `Proxy-Scheme` option from null-terminated string * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] scheme `Proxy-Scheme` value as buffer of UTF-8 code units, must be null-terminated * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option * * * Uses `strlen` to calculate the number of code units. * @see @ref unicoap_options_set_proxy_scheme */ static inline ssize_t unicoap_options_set_proxy_scheme_string(unicoap_options_t* options, char* scheme) { return unicoap_options_set_proxy_scheme(options, scheme, strlen(scheme)); } /** * @brief Removes the `Proxy-Scheme` option, if present * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_proxy_scheme(unicoap_options_t* options) { return unicoap_options_remove(options, UNICOAP_OPTION_PROXY_SCHEME); } /** @} */ /* Proxy-Scheme */ /* MARK: - Proxy-Uri */ /** * @name Proxy-Uri * @{ */ /** * @brief Retrieves the `Proxy-Uri` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] uri Pointer to value variable as buffer of UTF-8 code units * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_proxy_uri(const unicoap_options_t* options, const char** uri) { return unicoap_options_get(options, UNICOAP_OPTION_PROXY_URI, (const uint8_t**)uri); } /** * @brief Sets the `Proxy-Uri` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] uri `Proxy-Uri` value as buffer of UTF-8 code units * @param length Number of UTF-8 code units in @p uri, excluding null-terminator * (if present) in bytes * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option * * @pre @p uri must be at least of size 1 bytes * @pre @p uri size must not exceed 1034 bytes */ static inline ssize_t unicoap_options_set_proxy_uri(unicoap_options_t* options, char* uri, size_t length) { assert(length > 0 && length <= 1034); return unicoap_options_set(options, UNICOAP_OPTION_PROXY_URI, (uint8_t*)uri, length); } /** * @brief Sets the `Proxy-Uri` option from null-terminated string * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] uri `Proxy-Uri` value as buffer of UTF-8 code units, must be null-terminated * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option * * @pre @p uri must be at least of size 1 bytes * @pre @p uri size must not exceed 1034 bytes * * Uses `strlen` to calculate the number of code units. * @see @ref unicoap_options_set_proxy_uri */ static inline ssize_t unicoap_options_set_proxy_uri_string(unicoap_options_t* options, char* uri) { return unicoap_options_set_proxy_uri(options, uri, strlen(uri)); } /** * @brief Removes the `Proxy-Uri` option, if present * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_proxy_uri(unicoap_options_t* options) { return unicoap_options_remove(options, UNICOAP_OPTION_PROXY_URI); } /** @} */ /* Proxy-Uri */ /* MARK: - No-Response */ /** * @name No-Response * @{ */ /** * @brief Retrieves the `No-Response` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] value Pointer to value variable * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_no_response(const unicoap_options_t* options, uint8_t* value) { return unicoap_options_get_uint8(options, UNICOAP_OPTION_NO_RESPONSE, value); } /** * @brief Sets the `No-Response` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param value `No-Response` value * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option */ static inline ssize_t unicoap_options_set_no_response(unicoap_options_t* options, uint8_t value) { return unicoap_options_set_uint(options, UNICOAP_OPTION_NO_RESPONSE, (uint32_t)value); } /** * @brief Removes the `No-Response` option, if present * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_no_response(unicoap_options_t* options) { return unicoap_options_remove(options, UNICOAP_OPTION_NO_RESPONSE); } /** @} */ /* No-Response */ /* MARK: - If-Match */ /** * @name If-Match * @{ */ /** * @brief Retrieves the first `If-Match` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] value Pointer to value variable * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_first_if_match(const unicoap_options_t* options, const uint8_t** value) { return unicoap_options_get(options, UNICOAP_OPTION_IF_MATCH, value); } /** * @brief Gets the next `If-Match` option provided by the specified iterator * @memberof unicoap_options_t * * @param[in,out] iterator Option iterator * @param[out] value Pointer to a variable that will store next value * * @see @ref unicoap_options_iterator_t::unicoap_options_get_next_by_number * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-EBADOPT` Option corrupted * @retval `-1` if the iterator is finished */ static inline ssize_t unicoap_options_get_next_if_match(unicoap_options_iterator_t* iterator, const uint8_t** value) { return unicoap_options_get_next_by_number(iterator, UNICOAP_OPTION_IF_MATCH, value); } /** * @brief Adds `If-Match` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] value `If-Match` value * @param size Number of bytes in @p value in bytes * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * * @pre @p value size must not exceed 8 bytes */ static inline ssize_t unicoap_options_add_if_match(unicoap_options_t* options, uint8_t* value, size_t size) { assert(size <= 8); return unicoap_options_add(options, UNICOAP_OPTION_IF_MATCH, value, size); } /** * @brief Removes all `If-Match` options, if any * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_all_if_match(unicoap_options_t* options) { return unicoap_options_remove_all(options, UNICOAP_OPTION_IF_MATCH); } /** @} */ /* If-Match */ /* MARK: - ETag */ /** * @name ETag * @{ */ /** * @brief Retrieves the first `ETag` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] etag Pointer to value variable * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_first_etag(const unicoap_options_t* options, const uint8_t** etag) { return unicoap_options_get(options, UNICOAP_OPTION_ETAG, etag); } /** * @brief Gets the next `ETag` option provided by the specified iterator * @memberof unicoap_options_t * * @param[in,out] iterator Option iterator * @param[out] etag Pointer to a variable that will store next etag * * @see @ref unicoap_options_iterator_t::unicoap_options_get_next_by_number * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-EBADOPT` Option corrupted * @retval `-1` if the iterator is finished */ static inline ssize_t unicoap_options_get_next_etag(unicoap_options_iterator_t* iterator, const uint8_t** etag) { return unicoap_options_get_next_by_number(iterator, UNICOAP_OPTION_ETAG, etag); } /** * @brief Adds `ETag` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] etag `ETag` value * @param size Number of bytes in @p etag in bytes * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * * @pre @p etag must be at least of size 1 bytes * @pre @p etag size must not exceed 8 bytes */ static inline ssize_t unicoap_options_add_etag(unicoap_options_t* options, uint8_t* etag, size_t size) { assert(size > 0 && size <= 8); return unicoap_options_add(options, UNICOAP_OPTION_ETAG, etag, size); } /** * @brief Removes all `ETag` options, if any * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_etags(unicoap_options_t* options) { return unicoap_options_remove_all(options, UNICOAP_OPTION_ETAG); } /** @} */ /* ETag */ /* MARK: - Location-Path */ /** * @name Location-Path * @{ */ /** * @brief Retrieves the first `Location-Path` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] component Pointer to value variable as buffer of UTF-8 code units * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_first_location_path_component(const unicoap_options_t* options, const char** component) { return unicoap_options_get(options, UNICOAP_OPTION_LOCATION_PATH, (const uint8_t**)component); } /** * @brief Gets the next `Location-Path` option provided by the specified iterator * @memberof unicoap_options_t * * @param[in,out] iterator Option iterator * @param[out] component Pointer to a variable that will store next component * * @see @ref unicoap_options_iterator_t::unicoap_options_get_next_by_number * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-EBADOPT` Option corrupted * @retval `-1` if the iterator is finished */ static inline ssize_t unicoap_options_get_next_location_path_component(unicoap_options_iterator_t* iterator, const char** component) { return unicoap_options_get_next_by_number(iterator, UNICOAP_OPTION_LOCATION_PATH, (const uint8_t**)component); } /** * @brief Copies absolute location path into the given buffer * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[in,out] path Buffer of UTF-8 code units * @param capacity Capacity of @p path * * @returns Length of string value in bytes on success, negative error number otherwise * @retval `-EBADOPT` Option corrupted * @retval `-ENOBUFS` @p path lacks sufficient capacity to copy values * * @pre @p capacity must be greater than zero * * This function creates a string from all `Location-Path` options * by joining them with the `/` separator. * The string will bear the `/` prefix even if there is no `Location-Path` option. * The string will not be null-terminated. The resulting string uses UTF-8 encoding. */ static inline ssize_t unicoap_options_copy_location_path(const unicoap_options_t* options, char* path, size_t capacity) { assert(capacity > 0); *path = '/'; path += 1; capacity -= 1; int res = unicoap_options_copy_values_joined(options, UNICOAP_OPTION_LOCATION_PATH, (uint8_t*)path, capacity, '/'); return res < 0 ? res : res + 1; } /** * @brief Adds `Location-Path` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] component `Location-Path` value as buffer of UTF-8 code units * @param length Number of UTF-8 code units in @p component, excluding null-terminator * (if present) in bytes * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * */ static inline ssize_t unicoap_options_add_location_path_component(unicoap_options_t* options, char* component, size_t length) { return unicoap_options_add(options, UNICOAP_OPTION_LOCATION_PATH, (uint8_t*)component, length); } /** * @brief Adds `Location-Path` option from null-terminated string * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] component `Location-Path` value as buffer of UTF-8 code units, must be null-terminated * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * * * Uses `strlen` to calculate the number of code units. * @see @ref unicoap_options_add_location_path_component */ static inline ssize_t unicoap_options_add_location_path_component_string(unicoap_options_t* options, char* component) { return unicoap_options_add_location_path_component(options, component, strlen(component)); } /** * @brief Adds multiple `Location-Path` options from string * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] path as buffer of UTF-8 code units with values separated by `/` * @param length Number of UTF-8 code units in @p path, excluding null-terminator * (if present) in bytes * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * * If the string with the values you want to add _starts_ with the separator, * you can still use this function. */ static inline ssize_t unicoap_options_add_location_path(unicoap_options_t* options, char* path, size_t length) { return unicoap_options_add_values_joined(options, UNICOAP_OPTION_LOCATION_PATH, (uint8_t*)path, length, '/'); } /** * @brief Adds multiple `Location-Path` options from null-terminated string * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] path as null-terminated string of UTF-8 code units with values separated by `/` * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * * If the string with the values you want to add _starts_ with the separator, * you can still use this function. * Uses `strlen` to calculate the number of code units. * * @see @ref unicoap_options_add_location_path */ static inline ssize_t unicoap_options_add_location_path_string(unicoap_options_t* options, char* path) { return unicoap_options_add_location_path(options, path, strlen(path)); } /** * @brief Removes all `Location-Path` options, if any * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_location_path(unicoap_options_t* options) { return unicoap_options_remove_all(options, UNICOAP_OPTION_LOCATION_PATH); } /** @} */ /* Location-Path */ /* MARK: - Uri-Path */ /** * @name Uri-Path * @{ */ /** * @brief Retrieves the first `Uri-Path` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] component Pointer to value variable as buffer of UTF-8 code units * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_first_uri_path_component(const unicoap_options_t* options, const char** component) { return unicoap_options_get(options, UNICOAP_OPTION_URI_PATH, (const uint8_t**)component); } /** * @brief Gets the next `Uri-Path` option provided by the specified iterator * @memberof unicoap_options_t * * @param[in,out] iterator Option iterator * @param[out] component Pointer to a variable that will store next component * * @see @ref unicoap_options_iterator_t::unicoap_options_get_next_by_number * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-EBADOPT` Option corrupted * @retval `-1` if the iterator is finished */ static inline ssize_t unicoap_options_get_next_uri_path_component(unicoap_options_iterator_t* iterator, const char** component) { return unicoap_options_get_next_by_number(iterator, UNICOAP_OPTION_URI_PATH, (const uint8_t**)component); } /** * @brief Copies absolute URI path into the given buffer * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[in,out] path Buffer of UTF-8 code units * @param capacity Capacity of @p path * * @returns Length of string value in bytes on success, negative error number otherwise * @retval `-EBADOPT` Option corrupted * @retval `-ENOBUFS` @p path lacks sufficient capacity to copy values * * @pre @p capacity must be greater than zero * * This function creates a string from all `Uri-Path` options * by joining them with the `/` separator. * The string will bear the `/` prefix even if there is no `Uri-Path` option. * The string will not be null-terminated. The resulting string uses UTF-8 encoding. */ static inline ssize_t unicoap_options_copy_uri_path(const unicoap_options_t* options, char* path, size_t capacity) { assert(capacity > 0); *path = '/'; path += 1; capacity -= 1; int res = unicoap_options_copy_values_joined(options, UNICOAP_OPTION_URI_PATH, (uint8_t*)path, capacity, '/'); return res < 0 ? res : res + 1; } /** * @brief Adds `Uri-Path` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] component `Uri-Path` value as buffer of UTF-8 code units * @param length Number of UTF-8 code units in @p component, excluding null-terminator * (if present) in bytes * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * * @pre @p component size must not exceed 255 bytes */ static inline ssize_t unicoap_options_add_uri_path_component(unicoap_options_t* options, char* component, size_t length) { assert(length <= 255); return unicoap_options_add(options, UNICOAP_OPTION_URI_PATH, (uint8_t*)component, length); } /** * @brief Adds `Uri-Path` option from null-terminated string * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] component `Uri-Path` value as buffer of UTF-8 code units, must be null-terminated * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * * @pre @p component size must not exceed 255 bytes * * Uses `strlen` to calculate the number of code units. * @see @ref unicoap_options_add_uri_path_component */ static inline ssize_t unicoap_options_add_uri_path_component_string(unicoap_options_t* options, char* component) { return unicoap_options_add_uri_path_component(options, component, strlen(component)); } /** * @brief Adds multiple `Uri-Path` options from string * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] path as buffer of UTF-8 code units with values separated by `/` * @param length Number of UTF-8 code units in @p path, excluding null-terminator * (if present) in bytes * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * @pre components' size must not exceed 255 bytes * * If the string with the values you want to add _starts_ with the separator, * you can still use this function. */ static inline ssize_t unicoap_options_add_uri_path(unicoap_options_t* options, char* path, size_t length) { return unicoap_options_add_values_joined(options, UNICOAP_OPTION_URI_PATH, (uint8_t*)path, length, '/'); } /** * @brief Adds multiple `Uri-Path` options from null-terminated string * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] path as null-terminated string of UTF-8 code units with values separated by `/` * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * @pre components size must not exceed 255 bytes * * If the string with the values you want to add _starts_ with the separator, * you can still use this function. * Uses `strlen` to calculate the number of code units. * * @see @ref unicoap_options_add_uri_path */ static inline ssize_t unicoap_options_add_uri_path_string(unicoap_options_t* options, char* path) { return unicoap_options_add_uri_path(options, path, strlen(path)); } /** * @brief Removes all `Uri-Path` options, if any * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_uri_path(unicoap_options_t* options) { return unicoap_options_remove_all(options, UNICOAP_OPTION_URI_PATH); } /** @} */ /* Uri-Path */ /* MARK: - Uri-Query */ /** * @name Uri-Query * @{ */ /** * @brief Retrieves the first `Uri-Query` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] query Pointer to value variable as buffer of UTF-8 code units * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_first_uri_query(const unicoap_options_t* options, const char** query) { return unicoap_options_get(options, UNICOAP_OPTION_URI_QUERY, (const uint8_t**)query); } /** * @brief Gets the next `Uri-Query` option provided by the specified iterator * @memberof unicoap_options_t * * @param[in,out] iterator Option iterator * @param[out] query Pointer to a variable that will store next query * * @see @ref unicoap_options_iterator_t::unicoap_options_get_next_by_number * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-EBADOPT` Option corrupted * @retval `-1` if the iterator is finished */ static inline ssize_t unicoap_options_get_next_uri_query(unicoap_options_iterator_t* iterator, const char** query) { return unicoap_options_get_next_by_number(iterator, UNICOAP_OPTION_URI_QUERY, (const uint8_t**)query); } /** * @brief Gets the next `Uri-Query` option matching the given name, * potentially skipping any options in between. * * @memberof unicoap_options_t * * This method splits `Uri-Query` options at the `=` character. * * @param[in,out] iterator Option iterator * @param[in] name Name of query parameter to find * @param[out] value Pointer to a UTF-8 string variable that will store the entire option, * including the `name=` part * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-EBADOPT` Option corrupted * @retval `-1` if the iterator is finished */ static inline ssize_t unicoap_options_get_next_uri_query_by_name(unicoap_options_iterator_t* iterator, const char* name, const char** value) { return unicoap_options_get_next_query_by_name(iterator, UNICOAP_OPTION_URI_QUERY, name, value); } /** * @brief Retrieves the first `Uri-Query` option matching the given name, if present * @memberof unicoap_options_t * * This method splits `Uri-Query` options at the `=` character. * * @param[in] options Options to read from * @param[in] name Name of query parameter to find * @param[out] value Pointer to a UTF-8 string variable that will store the entire option, * including the `name=` part * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-EBADOPT` Option corrupted * @retval `-1` if the iterator is finished and no matching `Uri-Query` option was found * * @note If you already have an @ref unicoap_options_iterator_t instance allocated somewhere, use * it and call @ref unicoap_options_get_next_uri_query_by_name instead. */ static inline ssize_t unicoap_options_get_first_uri_query_by_name(unicoap_options_t* options, const char* name, const char** value) { unicoap_options_iterator_t iterator; unicoap_options_iterator_init(&iterator, options); return unicoap_options_get_next_uri_query_by_name(&iterator, name, value); } /** * @brief Copies URI query string into the given buffer * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[in,out] queries Buffer of UTF-8 code units * @param capacity Capacity of @p queries * * @returns Length of string value in bytes on success, negative error number otherwise * @retval `-EBADOPT` Option corrupted * @retval `-ENOBUFS` @p queries lacks sufficient capacity to copy values * * This function creates a string from all `Uri-Query` options * by joining them with the `&` separator. * The string will not be null-terminated. The resulting string uses UTF-8 encoding. */ static inline ssize_t unicoap_options_copy_uri_queries(const unicoap_options_t* options, char* queries, size_t capacity) { return unicoap_options_copy_values_joined(options, UNICOAP_OPTION_URI_QUERY, (uint8_t*)queries, capacity, '&'); } /** * @brief Adds `Uri-Query` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] query `Uri-Query` value as buffer of UTF-8 code units * @param length Number of UTF-8 code units in @p query, excluding null-terminator * (if present) in bytes * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * * @pre @p query size must not exceed 255 bytes */ static inline ssize_t unicoap_options_add_uri_query(unicoap_options_t* options, char* query, size_t length) { assert(length <= 255); return unicoap_options_add(options, UNICOAP_OPTION_URI_QUERY, (uint8_t*)query, length); } /** * @brief Adds `Uri-Query` option from null-terminated string * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] query `Uri-Query` value as buffer of UTF-8 code units, must be null-terminated * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * * @pre @p query size must not exceed 255 bytes * * Uses `strlen` to calculate the number of code units. * @see @ref unicoap_options_add_uri_query */ static inline ssize_t unicoap_options_add_uri_query_string(unicoap_options_t* options, char* query) { return unicoap_options_add_uri_query(options, query, strlen(query)); } /** * @brief Adds multiple `Uri-Query` options from string * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] queries as buffer of UTF-8 code units with values separated by `&` * @param length Number of UTF-8 code units in @p queries, excluding null-terminator * (if present) in bytes * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * @pre queries' size must not exceed 255 bytes * * If the string with the values you want to add _starts_ with the separator, * you can still use this function. */ static inline ssize_t unicoap_options_add_uri_queries(unicoap_options_t* options, char* queries, size_t length) { return unicoap_options_add_values_joined(options, UNICOAP_OPTION_URI_QUERY, (uint8_t*)queries, length, '&'); } /** * @brief Adds multiple `Uri-Query` options from null-terminated string * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] queries as null-terminated string of UTF-8 code units with values separated by `&` * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * @pre queries size must not exceed 255 bytes * * If the string with the values you want to add _starts_ with the separator, * you can still use this function. * Uses `strlen` to calculate the number of code units. * * @see @ref unicoap_options_add_uri_queries */ static inline ssize_t unicoap_options_add_uri_queries_string(unicoap_options_t* options, char* queries) { return unicoap_options_add_uri_queries(options, queries, strlen(queries)); } /** * @brief Removes all `Uri-Query` options, if any * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_uri_queries(unicoap_options_t* options) { return unicoap_options_remove_all(options, UNICOAP_OPTION_URI_QUERY); } /** @} */ /* Uri-Query */ /* MARK: - Location-Query */ /** * @name Location-Query * @{ */ /** * @brief Retrieves the first `Location-Query` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] query Pointer to value variable as buffer of UTF-8 code units * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_first_location_query(const unicoap_options_t* options, const char** query) { return unicoap_options_get(options, UNICOAP_OPTION_LOCATION_QUERY, (const uint8_t**)query); } /** * @brief Gets the next `Location-Query` option provided by the specified iterator * @memberof unicoap_options_t * * @param[in,out] iterator Option iterator * @param[out] query Pointer to a variable that will store next query * * @see @ref unicoap_options_iterator_t::unicoap_options_get_next_by_number * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-EBADOPT` Option corrupted * @retval `-1` if the iterator is finished */ static inline ssize_t unicoap_options_get_next_location_query(unicoap_options_iterator_t* iterator, const char** query) { return unicoap_options_get_next_by_number(iterator, UNICOAP_OPTION_LOCATION_QUERY, (const uint8_t**)query); } /** * @brief Gets the next `Location-Query` option matching the given name, * potentially skipping any options in between. * * @memberof unicoap_options_t * * This method splits `Location-Query` options at the `=` character. * * @param[in,out] iterator Option iterator * @param[in] name Name of query parameter to find * @param[out] value Pointer to a UTF-8 string variable that will store the entire option, * including the `name=` part * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-EBADOPT` Option corrupted * @retval `-1` if the iterator is finished */ static inline ssize_t unicoap_options_get_next_location_query_by_name(unicoap_options_iterator_t* iterator, const char* name, const char** value) { return unicoap_options_get_next_query_by_name(iterator, UNICOAP_OPTION_LOCATION_QUERY, name, value); } /** * @brief Retrieves the first `Location-Query` option matching the given name, if present * @memberof unicoap_options_t * * This method splits `Location-Query` options at the `=` character. * * @param[in] options Options to read from * @param[in] name Name of query parameter to find * @param[out] value Pointer to a UTF-8 string variable that will store the entire option, * including the `name=` part * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-EBADOPT` Option corrupted * @retval `-1` if the iterator is finished and no matching `Location-Query` option was found * * @note If you already have an @ref unicoap_options_iterator_t instance allocated somewhere, use * it and call @ref unicoap_options_get_next_location_query_by_name instead. */ static inline ssize_t unicoap_options_get_first_location_query_by_name(unicoap_options_t* options, const char* name, const char** value) { unicoap_options_iterator_t iterator; unicoap_options_iterator_init(&iterator, options); return unicoap_options_get_next_location_query_by_name(&iterator, name, value); } /** * @brief Copies location query string into the given buffer * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[in,out] queries Buffer of UTF-8 code units * @param capacity Capacity of @p queries * * @returns Length of string value in bytes on success, negative error number otherwise * @retval `-EBADOPT` Option corrupted * @retval `-ENOBUFS` @p queries lacks sufficient capacity to copy values * * This function creates a string from all `Location-Query` options * by joining them with the `&` separator. * The string will not be null-terminated. The resulting string uses UTF-8 encoding. */ static inline ssize_t unicoap_options_copy_location_queries(const unicoap_options_t* options, char* queries, size_t capacity) { return unicoap_options_copy_values_joined(options, UNICOAP_OPTION_LOCATION_QUERY, (uint8_t*)queries, capacity, '&'); } /** * @brief Adds `Location-Query` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] query `Location-Query` value as buffer of UTF-8 code units * @param length Number of UTF-8 code units in @p query, excluding null-terminator * (if present) in bytes * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * * @pre @p query size must not exceed 255 bytes */ static inline ssize_t unicoap_options_add_location_query(unicoap_options_t* options, char* query, size_t length) { assert(length <= 255); return unicoap_options_add(options, UNICOAP_OPTION_LOCATION_QUERY, (uint8_t*)query, length); } /** * @brief Adds `Location-Query` option from null-terminated string * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] query `Location-Query` value as buffer of UTF-8 code units, must be null-terminated * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * * @pre @p query size must not exceed 255 bytes * * Uses `strlen` to calculate the number of code units. * @see @ref unicoap_options_add_location_query */ static inline ssize_t unicoap_options_add_location_query_string(unicoap_options_t* options, char* query) { return unicoap_options_add_location_query(options, query, strlen(query)); } /** * @brief Adds multiple `Location-Query` options from string * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] queries as buffer of UTF-8 code units with values separated by `&` * @param length Number of UTF-8 code units in @p queries, excluding null-terminator * (if present) in bytes * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * @pre queries' size must not exceed 255 bytes * * If the string with the values you want to add _starts_ with the separator, * you can still use this function. */ static inline ssize_t unicoap_options_add_location_queries(unicoap_options_t* options, char* queries, size_t length) { return unicoap_options_add_values_joined(options, UNICOAP_OPTION_LOCATION_QUERY, (uint8_t*)queries, length, '&'); } /** * @brief Adds multiple `Location-Query` options from null-terminated string * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param[in] queries as null-terminated string of UTF-8 code units with values separated by `&` * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to add options * @pre queries size must not exceed 255 bytes * * If the string with the values you want to add _starts_ with the separator, * you can still use this function. * Uses `strlen` to calculate the number of code units. * * @see @ref unicoap_options_add_location_queries */ static inline ssize_t unicoap_options_add_location_queries_string(unicoap_options_t* options, char* queries) { return unicoap_options_add_location_queries(options, queries, strlen(queries)); } /** * @brief Removes all `Location-Query` options, if any * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_location_queries(unicoap_options_t* options) { return unicoap_options_remove_all(options, UNICOAP_OPTION_LOCATION_QUERY); } /** @} */ /* Location-Query */ /* MARK: - Observe */ /** * @name Observe * @{ */ /** @brief Observe value for registering for notifications */ #define UNICOAP_OBSERVE_OPTION_REGISTER (0) /** @brief Observe value for cancelling a registration for notifications */ #define UNICOAP_OBSERVE_OPTION_DEREGISTER (1) /** * @brief Retrieves the `Observe` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] observe Pointer to value variable * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_observe(const unicoap_options_t* options, uint32_t* observe) { return unicoap_options_get_uint24(options, UNICOAP_OPTION_OBSERVE, observe); } /** * @brief Sets the `Observe` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param observe `Observe` value * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option */ static inline ssize_t unicoap_options_set_observe(unicoap_options_t* options, uint32_t observe) { return unicoap_options_set_uint(options, UNICOAP_OPTION_OBSERVE, observe); } /** * @brief Removes the `Observe` option, if present * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_observe(unicoap_options_t* options) { return unicoap_options_remove(options, UNICOAP_OPTION_OBSERVE); } /** * @brief Sets the `Observe` option to a randomly generated value * @memberof unicoap_options_t * * @param[in] options Options to read from * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option */ int unicoap_options_set_observe_generated(unicoap_options_t* options); /** @} */ /* Observe */ /* MARK: - Block-wise Transfers */ /** * @name Block-wise Transfers * @{ */ /** * @brief Sentinel value for @ref unicoap_block_option_t indicating an uninitialized value * @note This constant occupies 4 bytes and does thus not represent a valid `Block1` or `Block2` * value. */ #define UNICOAP_BLOCK_OPTION_NONE (0x0f000000) /** * @brief `Block1` and `Block2` option value */ typedef uint32_t unicoap_block_option_t; /** * @brief Retrieves a `Block1` or `Block2` option * @memberof unicoap_options_t * * @param[in] options Options to read from * @param number Option number (@ref UNICOAP_OPTION_BLOCK1 or @ref UNICOAP_OPTION_BLOCK2) * @param[out] block Pointer to variable that will store `Block1` or `Block2` value * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_block(const unicoap_options_t* options, unicoap_option_number_t number, unicoap_block_option_t* block) { return unicoap_options_get_uint24(options, number, block); } /** * @brief Sets the `Block1` or `Block2` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param number Option number (@ref UNICOAP_OPTION_BLOCK1 or @ref UNICOAP_OPTION_BLOCK2) * @param block `Block1` or `Block2` value * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option */ static inline int unicoap_options_set_block(unicoap_options_t* options, unicoap_option_number_t number, unicoap_block_option_t block) { assert(block <= UNICOAP_UINT24_MAX); return unicoap_options_set_uint(options, number, block); } /** * @brief Retrieves the `Block1` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] block Pointer to value variable * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_block1(const unicoap_options_t* options, unicoap_block_option_t* block) { return unicoap_options_get_block(options, UNICOAP_OPTION_BLOCK1, block); } /** * @brief Sets the `Block1` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param block `Block1` value * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option */ static inline ssize_t unicoap_options_set_block1(unicoap_options_t* options, unicoap_block_option_t block) { return unicoap_options_set_block(options, UNICOAP_OPTION_BLOCK1, block); } /** * @brief Removes the `Block1` option, if present * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_block1(unicoap_options_t* options) { return unicoap_options_remove(options, UNICOAP_OPTION_BLOCK1); } /** * @brief Retrieves the `Block2` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] block Pointer to value variable * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_block2(const unicoap_options_t* options, unicoap_block_option_t* block) { return unicoap_options_get_block(options, UNICOAP_OPTION_BLOCK2, block); } /** * @brief Sets the `Block2` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param block `Block2` value * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option */ static inline ssize_t unicoap_options_set_block2(unicoap_options_t* options, unicoap_block_option_t block) { return unicoap_options_set_block(options, UNICOAP_OPTION_BLOCK2, block); } /** * @brief Removes the `Block2` option, if present * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_block2(unicoap_options_t* options) { return unicoap_options_remove(options, UNICOAP_OPTION_BLOCK2); } /** * @brief Retrieves the `Size1` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] size Pointer to value variable * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_size1(const unicoap_options_t* options, uint32_t* size) { return unicoap_options_get_uint32(options, UNICOAP_OPTION_SIZE1, size); } /** * @brief Sets the `Size1` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param size `Size1` value * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option */ static inline ssize_t unicoap_options_set_size1(unicoap_options_t* options, uint32_t size) { return unicoap_options_set_uint(options, UNICOAP_OPTION_SIZE1, size); } /** * @brief Removes the `Size1` option, if present * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_size1(unicoap_options_t* options) { return unicoap_options_remove(options, UNICOAP_OPTION_SIZE1); } /** * @brief Retrieves the `Size2` option, if present * @memberof unicoap_options_t * * @param[in] options Options to read from * @param[out] size Pointer to value variable * * @returns Size of option value in bytes on success, negative error number otherwise * @retval `-ENOENT` Option not found * @retval `-EBADOPT` Option corrupted */ static inline ssize_t unicoap_options_get_size2(const unicoap_options_t* options, uint32_t* size) { return unicoap_options_get_uint32(options, UNICOAP_OPTION_SIZE2, size); } /** * @brief Sets the `Size2` option * @memberof unicoap_options_t * * @param[in,out] options Options to write to * @param size `Size2` value * * @returns Zero on success, negative error number otherwise * @retval `-ENOBUFS` Options buffer lacks sufficient capacity to set option */ static inline ssize_t unicoap_options_set_size2(unicoap_options_t* options, uint32_t size) { return unicoap_options_set_uint(options, UNICOAP_OPTION_SIZE2, size); } /** * @brief Removes the `Size2` option, if present * @memberof unicoap_options_t * * @param[in,out] options Options to write to * * @returns Zero on success, negative error number otherwise */ static inline int unicoap_options_remove_size2(unicoap_options_t* options) { return unicoap_options_remove(options, UNICOAP_OPTION_SIZE2); } /** @} */ /* Block-wise Transfers */ /** @} */ #ifdef __cplusplus } #endif /** @} */