#include "bits.h"
#include "bits.h"
#include "pdu.h"
#include "pdu.h"
#define COAP_OPTION_H_
#define COAP_OPT_FILTER_SHORT 6
/** * The number of option types below 256 that can be stored in an * option filter. COAP_OPT_FILTER_SHORT + COAP_OPT_FILTER_LONG must be * at most 16. Each coap_option_filter_t object reserves * ((COAP_OPT_FILTER_SHORT + 1) / 2) * 2 bytes for short options. */
#define COAP_OPT_FILTER_LONG 2
/** * The number of option types above 255 that can be stored in an * option filter. COAP_OPT_FILTER_SHORT + COAP_OPT_FILTER_LONG must be * at most 16. Each coap_option_filter_t object reserves * COAP_OPT_FILTER_LONG * 2 bytes for short options. */
#define COAP_OPT_FILTER_SIZE \
(((COAP_OPT_FILTER_SHORT + 1) >> 1) + COAP_OPT_FILTER_LONG) +1
/** The number of elements in coap_opt_filter_t. */
#define COAP_OPT_ALL NULL
/** Pre-defined filter that includes all options. */
size_t coap_opt_parse(const coap_opt_t *opt,
size_t length,
coap_option_t *result);
/** * Parses the option pointed to by @p opt into @p result. This function returns * the number of bytes that have been parsed, or @c 0 on error. An error is * signaled when illegal delta or length values are encountered or when option * parsing would result in reading past the option (i.e. beyond opt + length). * * @param opt The beginning of the option to parse. * @param length The maximum length of @p opt. * @param result A pointer to the coap_option_t structure that is filled with * actual values iff coap_opt_parse() > 0. * @return The number of bytes parsed or @c 0 on error. */
size_t coap_opt_size(const coap_opt_t *opt);
/** * Returns the size of the given option, taking into account a possible option * jump. * * @param opt An option jump or the beginning of the option. * @return The number of bytes between @p opt and the end of the option * starting at @p opt. In case of an error, this function returns * @c 0 as options need at least one byte storage space. */
int coap_option_filter_set(coap_opt_filter_t filter, uint16_t type);
/** * Sets the corresponding entry for @p type in @p filter. This * function returns @c 1 if bit was set or @c 0 on error (i.e. when * the given type does not fit in the filter). * * @param filter The filter object to change. * @param type The type for which the bit should be set. * * @return @c 1 if bit was set, @c 0 otherwise. */
int coap_option_filter_unset(coap_opt_filter_t filter, uint16_t type);
/** * Clears the corresponding entry for @p type in @p filter. This * function returns @c 1 if bit was set or @c 0 on error (i.e. when * the given type does not fit in the filter). * * @param filter The filter object to change. * @param type The type that should be cleared from the filter. * * @return @c 1 if bit was set, @c 0 otherwise. */
int coap_option_filter_get(coap_opt_filter_t filter, uint16_t type);
/** * Checks if @p type is contained in @p filter. This function returns * @c 1 if found, @c 0 if not, or @c -1 on error (i.e. when the given * type does not fit in the filter). * * @param filter The filter object to search. * @param type The type to search for. * * @return @c 1 if @p type was found, @c 0 otherwise, or @c -1 on error. */
size_t coap_opt_setheader(coap_opt_t *opt,
size_t maxlen,
uint16_t delta,
size_t length);
/** * Encodes the given delta and length values into @p opt. This function returns * the number of bytes that were required to encode @p delta and @p length or @c * 0 on error. Note that the result indicates by how many bytes @p opt must be * advanced to encode the option value. * * @param opt The option buffer space where @p delta and @p length are * written. * @param maxlen The maximum length of @p opt. * @param delta The actual delta value to encode. * @param length The actual length value to encode. * * @return The number of bytes used or @c 0 on error. */
size_t coap_opt_encode_size(uint16_t delta, size_t length);
/** * Compute storage bytes needed for an option with given @p delta and * @p length * * @param delta The option delta. * @param length The option length. * * @return The number of bytes required to encode this option. */
size_t coap_opt_encode(coap_opt_t *opt,
size_t n,
uint16_t delta,
const uint8_t *val,
size_t length);
/** * Encodes option with given @p delta into @p opt. This function returns the * number of bytes written to @p opt or @c 0 on error. This happens especially * when @p opt does not provide sufficient space to store the option value, * delta, and option jumps when required. * * @param opt The option buffer space where @p val is written. * @param n Maximum length of @p opt. * @param delta The option delta. * @param val The option value to copy into @p opt. * @param length The actual length of @p val. * * @return The number of bytes that have been written to @p opt or @c 0 on * error. The return value will always be less than @p n. */
int coap_add_optlist_pdu(coap_pdu_t *pdu, coap_optlist_t** optlist_chain);
/** * The current optlist of @p optlist_chain is first sorted (as per RFC7272 * ordering requirements) and then added to the @p pdu. * * @param pdu The pdu to add the options to from the chain list * @param optlist_chain The chained list of optlist to add to the pdu * * @return @c 1 if succesful or @c 0 if failure; */
int coap_insert_optlist(coap_optlist_t **optlist_chain,
coap_optlist_t *optlist);
/** * Adds @p optlist to the given @p optlist_chain. The optlist_chain variable * be set to NULL before the initial call to coap_insert_optlist(). * The optlist_chain will need to be deleted using coap_delete_optlist() * when no longer required. * * @param optlist_chain The chain to add optlist to * @param optlist The optlist to add to the queue * * @return @c 1 if successful, @c 0 otherwise. */
void coap_delete_optlist(coap_optlist_t *optlist_chain);
/** * Removes all entries from the @p optlist_chain, freeing off their * memory usage. * * @param optlist_chain The optlist chain to remove all the entries from */
coap_opt_iterator_t *coap_option_iterator_init(const coap_pdu_t *pdu,
coap_opt_iterator_t *oi,
const coap_opt_filter_t filter);
/** * Initializes the given option iterator @p oi to point to the beginning of the * @p pdu's option list. This function returns @p oi on success, @c NULL * otherwise (i.e. when no options exist). Note that a length check on the * option list must be performed before coap_option_iterator_init() is called. * * @param pdu The PDU the options of which should be walked through. * @param oi An iterator object that will be initilized. * @param filter An optional option type filter. * With @p type != @c COAP_OPT_ALL, coap_option_next() * will return only options matching this bitmask. * Fence-post options @c 14, @c 28, @c 42, ... are always * skipped. * * @return The iterator object @p oi on success, @c NULL otherwise. */
coap_opt_t *coap_option_next(coap_opt_iterator_t *oi);
/** * Updates the iterator @p oi to point to the next option. This function returns * a pointer to that option or @c NULL if no more options exist. The contents of * @p oi will be updated. In particular, @c oi->n specifies the current option's * ordinal number (counted from @c 1), @c oi->type is the option's type code, * and @c oi->option points to the beginning of the current option itself. When * advanced past the last option, @c oi->option will be @c NULL. * * Note that options are skipped whose corresponding bits in the filter * specified with coap_option_iterator_init() are @c 0. Options with type codes * that do not fit in this filter hence will always be returned. * * @param oi The option iterator to update. * * @return The next option or @c NULL if no more options exist. */
coap_opt_t *coap_check_option(coap_pdu_t *pdu,
uint16_t type,
coap_opt_iterator_t *oi);
/** * Retrieves the first option of type @p type from @p pdu. @p oi must point to a * coap_opt_iterator_t object that will be initialized by this function to * filter only options with code @p type. This function returns the first option * with this type, or @c NULL if not found. * * @param pdu The PDU to parse for options. * @param type The option type code to search for. * @param oi An iterator object to use. * * @return A pointer to the first option of type @p type, or @c NULL if * not found. */
uint16_t coap_opt_delta(const coap_opt_t *opt);
/** * Decodes the delta value of the next option. This function returns the number * of bytes read or @c 0 on error. The caller of this function must ensure that * it does not read over the boundaries of @p opt (e.g. by calling * coap_opt_check_delta(). * * @param opt The option to examine. * * @return The number of bytes read or @c 0 on error. */
uint16_t coap_opt_length(const coap_opt_t *opt);
/** * Returns the length of the given option. @p opt must point to an option jump * or the beginning of the option. This function returns @c 0 when @p opt is not * an option or the actual length of @p opt (which can be @c 0 as well). * * @note {The rationale for using @c 0 in case of an error is that in most * contexts, the result of this function is used to skip the next * coap_opt_length() bytes.} * * @param opt The option whose length should be returned. * * @return The option's length or @c 0 when undefined. */
coap_optlist_t *coap_new_optlist(uint16_t number,
size_t length,
const uint8_t *data);
/** * Create a new optlist entry. * * @param number The option number (COAP_OPTION_*) * @param length The option length * @param data The option value data * * @return A pointer to the new optlist entry, or @c NULL if error */
const uint8_t *coap_opt_value(const coap_opt_t *opt);
/** * Returns a pointer to the value of the given option. @p opt must point to an * option jump or the beginning of the option. This function returns @c NULL if * @p opt is not a valid option. * * @param opt The option whose value should be returned. * * @return A pointer to the option value or @c NULL on error. */
typedef uint8_t coap_opt_t;
#define PCHAR(p) ((coap_opt_t *)(p))
/** * Use byte-oriented access methods here because sliding a complex struct * coap_opt_t over the data buffer may cause bus error on certain platforms. */
typedef struct {
uint16_t delta;
size_t length;
const uint8_t *value;
} coap_option_t;
/** * Representation of CoAP options. */
typedef uint16_t coap_opt_filter_t[COAP_OPT_FILTER_SIZE];
/** * Fixed-size vector we use for option filtering. It is large enough * to hold COAP_OPT_FILTER_SHORT entries with an option number between * 0 and 255, and COAP_OPT_FILTER_LONG entries with an option number * between 256 and 65535. Its internal structure is * * @code struct { uint16_t mask; uint16_t long_opts[COAP_OPT_FILTER_LONG]; uint8_t short_opts[COAP_OPT_FILTER_SHORT]; } * @endcode * * The first element contains a bit vector that indicates which fields * in the remaining array are used. The first COAP_OPT_FILTER_LONG * bits correspond to the long option types that are stored in the * elements from index 1 to COAP_OPT_FILTER_LONG. The next * COAP_OPT_FILTER_SHORT bits correspond to the short option types * that are stored in the elements from index COAP_OPT_FILTER_LONG + 1 * to COAP_OPT_FILTER_LONG + COAP_OPT_FILTER_SHORT. The latter * elements are treated as bytes. */
typedef struct {
size_t length; /**< remaining length of PDU */
uint16_t type; /**< decoded option type */
unsigned int bad:1; /**< iterator object is ok if not set */
unsigned int filtered:1; /**< denotes whether or not filter is used */
coap_opt_t *next_option; /**< pointer to the unparsed next option */
coap_opt_filter_t filter; /**< option filter */
} coap_opt_iterator_t;
/** * Iterator to run through PDU options. This object must be * initialized with coap_option_iterator_init(). Call * coap_option_next() to walk through the list of options until * coap_option_next() returns @c NULL. * * @code * coap_opt_t *option; * coap_opt_iterator_t opt_iter; * coap_option_iterator_init(pdu, &opt_iter, COAP_OPT_ALL); * * while ((option = coap_option_next(&opt_iter))) { * ... do something with option ... * } * @endcode */
typedef struct coap_optlist_t {
struct coap_optlist_t *next; /**< next entry in the optlist chain */
uint16_t number; /**< the option number (no delta coding) */
size_t length; /**< the option value length */
uint8_t *data; /**< the option data */
} coap_optlist_t;
/** * Representation of chained list of CoAP options to install. * * @code * coap_optlist_t *optlist_chain = NULL; * coap_pdu_t *pdu = coap_new_pdu(session); * * ... other set up code ... * coap_insert_optlist(&optlist_chain, coap_new_optlist(COAP_OPTION_OBSERVE, * COAP_OBSERVE_ESTABLISH, NULL)); * * coap_add_optlist_pdu(pdu, &optlist_chain); * ... other code ... * coap_delete_optlist(optlist_chain); * @endcode */