libcoap  4.2.0
option.h File Reference

Helpers for handling options in CoAP PDUs. More...

#include "bits.h"
#include "pdu.h"
+ Include dependency graph for option.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  coap_option_t
 Representation of CoAP options. More...
 
struct  coap_opt_iterator_t
 Iterator to run through PDU options. More...
 
struct  coap_optlist_t
 Representation of chained list of CoAP options to install. More...
 

Macros

#define PCHAR(p)   ((coap_opt_t *)(p))
 
#define COAP_OPT_FILTER_SHORT   6
 The number of option types below 256 that can be stored in an option filter. More...
 
#define COAP_OPT_FILTER_LONG   2
 The number of option types above 255 that can be stored in an option filter. More...
 
#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. More...
 
#define COAP_OPT_ALL   NULL
 Pre-defined filter that includes all options. More...
 

Typedefs

typedef uint8_t coap_opt_t
 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. More...
 
typedef uint16_t coap_opt_filter_t[COAP_OPT_FILTER_SIZE]
 Fixed-size vector we use for option filtering. More...
 
typedef struct coap_optlist_t coap_optlist_t
 Representation of chained list of CoAP options to install. More...
 

Functions

size_t coap_opt_parse (const coap_opt_t *opt, size_t length, coap_option_t *result)
 Parses the option pointed to by opt into result. More...
 
size_t coap_opt_size (const coap_opt_t *opt)
 Returns the size of the given option, taking into account a possible option jump. More...
 
COAP_STATIC_INLINE void coap_option_filter_clear (coap_opt_filter_t f)
 Clears filter f. More...
 
int coap_option_filter_set (coap_opt_filter_t filter, uint16_t type)
 Sets the corresponding entry for type in filter. More...
 
int coap_option_filter_unset (coap_opt_filter_t filter, uint16_t type)
 Clears the corresponding entry for type in filter. More...
 
int coap_option_filter_get (coap_opt_filter_t filter, uint16_t type)
 Checks if type is contained in filter. More...
 
COAP_STATIC_INLINE int coap_option_setb (coap_opt_filter_t filter, uint16_t type)
 Sets the corresponding bit for type in filter. More...
 
COAP_STATIC_INLINE int coap_option_clrb (coap_opt_filter_t filter, uint16_t type)
 Clears the corresponding bit for type in filter. More...
 
COAP_STATIC_INLINE int coap_option_getb (coap_opt_filter_t filter, uint16_t type)
 Gets the corresponding bit for type in filter. More...
 
coap_opt_iterator_tcoap_option_iterator_init (const coap_pdu_t *pdu, coap_opt_iterator_t *oi, const coap_opt_filter_t filter)
 Initializes the given option iterator oi to point to the beginning of the pdu's option list. More...
 
coap_opt_tcoap_option_next (coap_opt_iterator_t *oi)
 Updates the iterator oi to point to the next option. More...
 
coap_opt_tcoap_check_option (coap_pdu_t *pdu, uint16_t type, coap_opt_iterator_t *oi)
 Retrieves the first option of type type from pdu. More...
 
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 opt. More...
 
size_t coap_opt_encode_size (uint16_t delta, size_t length)
 Compute storage bytes needed for an option with given delta and length. More...
 
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 delta into opt. More...
 
uint16_t coap_opt_delta (const coap_opt_t *opt)
 Decodes the delta value of the next option. More...
 
uint16_t coap_opt_length (const coap_opt_t *opt)
 Returns the length of the given option. More...
 
const uint8_tcoap_opt_value (const coap_opt_t *opt)
 Returns a pointer to the value of the given option. More...
 
coap_optlist_tcoap_new_optlist (uint16_t number, size_t length, const uint8_t *data)
 Create a new optlist entry. More...
 
int coap_add_optlist_pdu (coap_pdu_t *pdu, coap_optlist_t **optlist_chain)
 The current optlist of optlist_chain is first sorted (as per RFC7272 ordering requirements) and then added to the pdu. More...
 
int coap_insert_optlist (coap_optlist_t **optlist_chain, coap_optlist_t *optlist)
 Adds optlist to the given optlist_chain. More...
 
void coap_delete_optlist (coap_optlist_t *optlist_chain)
 Removes all entries from the optlist_chain, freeing off their memory usage. More...
 

Detailed Description

Helpers for handling options in CoAP PDUs.

Definition in file option.h.

Macro Definition Documentation

◆ PCHAR

#define PCHAR (   p)    ((coap_opt_t *)(p))

Definition at line 26 of file option.h.

Typedef Documentation

◆ coap_opt_t

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.

Definition at line 25 of file option.h.

◆ coap_optlist_t

Representation of chained list of CoAP options to install.

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_add_optlist_pdu(pdu, &optlist_chain);
... other code ...
coap_delete_optlist(optlist_chain);

Function Documentation

◆ coap_add_optlist_pdu()

int coap_add_optlist_pdu ( coap_pdu_t pdu,
coap_optlist_t **  optlist_chain 
)

The current optlist of optlist_chain is first sorted (as per RFC7272 ordering requirements) and then added to the pdu.

Parameters
pduThe pdu to add the options to from the chain list
optlist_chainThe chained list of optlist to add to the pdu
Returns
1 if succesful or 0 if failure;

Definition at line 584 of file option.c.

+ Here is the call graph for this function:

◆ coap_delete_optlist()

void coap_delete_optlist ( coap_optlist_t optlist_chain)

Removes all entries from the optlist_chain, freeing off their memory usage.

Parameters
optlist_chainThe optlist chain to remove all the entries from

Definition at line 621 of file option.c.

+ Here is the call graph for this function:

◆ coap_insert_optlist()

int coap_insert_optlist ( coap_optlist_t **  optlist_chain,
coap_optlist_t optlist 
)

Adds optlist to the given 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.

Parameters
optlist_chainThe chain to add optlist to
optlistThe optlist to add to the queue
Returns
1 if successful, 0 otherwise.

Definition at line 600 of file option.c.

◆ coap_new_optlist()

coap_optlist_t* coap_new_optlist ( uint16_t  number,
size_t  length,
const uint8_t data 
)

Create a new optlist entry.

Parameters
numberThe option number (COAP_OPTION_*)
lengthThe option length
dataThe option value data
Returns
A pointer to the new optlist entry, or NULL if error

Definition at line 551 of file option.c.

+ Here is the call graph for this function:

◆ coap_opt_parse()

size_t coap_opt_parse ( const coap_opt_t opt,
size_t  length,
coap_option_t result 
)

Parses the option pointed to by opt into result.

This function returns the number of bytes that have been parsed, or 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).

Parameters
optThe beginning of the option to parse.
lengthThe maximum length of opt.
resultA pointer to the coap_option_t structure that is filled with actual values iff coap_opt_parse() > 0.
Returns
The number of bytes parsed or 0 on error.

Definition at line 46 of file option.c.

+ Here is the caller graph for this function:

◆ coap_opt_size()

size_t coap_opt_size ( const coap_opt_t opt)

Returns the size of the given option, taking into account a possible option jump.

Parameters
optAn option jump or the beginning of the option.
Returns
The number of bytes between opt and the end of the option starting at opt. In case of an error, this function returns 0 as options need at least one byte storage space.

Definition at line 321 of file option.c.

+ Here is the call graph for this function: