libcoap  4.3.0rc3
Option Filters

API functions for access option filters. More...

Data Structures

struct  coap_opt_filter_t
 
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 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_ALL   NULL
 Pre-defined filter that includes all options. More...
 

Typedefs

typedef struct coap_opt_filter_t coap_opt_filter_t
 
typedef struct coap_optlist_t coap_optlist_t
 Representation of chained list of CoAP options to install. More...
 

Functions

void coap_option_filter_clear (coap_opt_filter_t *filter)
 Clears filter filter. More...
 
int coap_option_filter_set (coap_opt_filter_t *filter, coap_option_num_t number)
 Sets the corresponding entry for number in filter. More...
 
int coap_option_filter_unset (coap_opt_filter_t *filter, coap_option_num_t number)
 Clears the corresponding entry for number in filter. More...
 
int coap_option_filter_get (coap_opt_filter_t *filter, coap_option_num_t number)
 Checks if number is contained 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 (const coap_pdu_t *pdu, coap_option_num_t number, coap_opt_iterator_t *oi)
 Retrieves the first option of number number 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...
 
uint32_t coap_opt_length (const coap_opt_t *opt)
 Returns the length of the given option. More...
 
const uint8_t * coap_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

API functions for access option filters.

Macro Definition Documentation

◆ COAP_OPT_ALL

#define COAP_OPT_ALL   NULL

Pre-defined filter that includes all options.

Definition at line 107 of file option.h.

◆ COAP_OPT_FILTER_LONG

#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.

Definition at line 85 of file option.h.

◆ COAP_OPT_FILTER_SHORT

#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.

Definition at line 77 of file option.h.

Typedef Documentation

◆ coap_opt_filter_t

◆ 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);
#define COAP_OBSERVE_ESTABLISH
The value COAP_OBSERVE_ESTABLISH in a GET/FETCH request option COAP_OPTION_OBSERVE indicates a new ob...
Definition: subscribe.h:30
coap_optlist_t * coap_new_optlist(uint16_t number, size_t length, const uint8_t *data)
Create a new optlist entry.
Definition: option.c:506
int coap_add_optlist_pdu(coap_pdu_t *pdu, coap_optlist_t **options)
The current optlist of optlist_chain is first sorted (as per RFC7272 ordering requirements) and then ...
Definition: option.c:547
coap_pdu_t * coap_new_pdu(coap_pdu_type_t type, coap_pdu_code_t code, coap_session_t *session)
Creates a new CoAP PDU.
Definition: pdu.c:130
#define COAP_OPTION_OBSERVE
Definition: pdu.h:109
Representation of chained list of CoAP options to install.
Definition: option.h:327
structure for CoAP PDUs token, if any, follows the fixed size header, then options until payload mark...

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 547 of file option.c.

+ Here is the call graph for this function:

◆ coap_check_option()

coap_opt_t* coap_check_option ( const coap_pdu_t pdu,
coap_option_num_t  number,
coap_opt_iterator_t oi 
)

Retrieves the first option of number number from pdu.

oi must point to a coap_opt_iterator_t object that will be initialized by this function to filter only options with number number. This function returns the first option with this number, or NULL if not found.

Parameters
pduThe PDU to parse for options.
numberThe option number to search for.
oiAn iterator object to use.
Returns
A pointer to the first option of number number, or NULL if not found.

Definition at line 196 of file option.c.

+ Here is the call graph for this function:
+ Here is the caller 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 584 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 563 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.

Note: Where possible, the option data needs to be stripped of leading zeros (big endian) to reduce the amount of data needed in the PDU, as well as in some cases the maximum data size of an opton can be exceeded if not stripped and hence be illegal. This is done by using coap_encode_var_safe() or coap_encode_var_safe8().

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 506 of file option.c.

+ Here is the call graph for this function:

◆ coap_opt_encode()

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.

This function returns the number of bytes written to opt or 0 on error. This happens especially when opt does not provide sufficient space to store the option value, delta, and option jumps when required.

Parameters
optThe option buffer space where val is written.
nMaximum length of opt.
deltaThe option delta.
valThe option value to copy into opt.
lengthThe actual length of val.
Returns
The number of bytes that have been written to opt or 0 on error. The return value will always be less than n.

Definition at line 369 of file option.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_opt_encode_size()

size_t coap_opt_encode_size ( uint16_t  delta,
size_t  length 
)

Compute storage bytes needed for an option with given delta and length.

Parameters
deltaThe option delta.
lengthThe option length.
Returns
The number of bytes required to encode this option.

Definition at line 348 of file option.c.

+ Here is the caller graph for this function:

◆ coap_opt_length()

uint32_t coap_opt_length ( const coap_opt_t opt)

Returns the length of the given option.

opt must point to an option jump or the beginning of the option. This function returns 0 when opt is not an option or the actual length of opt (which can be 0 as well).

Note
{The rationale for using 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.}
Parameters
optThe option whose length should be returned.
Returns
The option's length or 0 when undefined.

Definition at line 209 of file option.c.

+ Here is the caller graph for this function:

◆ coap_opt_setheader()

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.

This function returns the number of bytes that were required to encode delta and length or 0 on error. Note that the result indicates by how many bytes opt must be advanced to encode the option value.

Parameters
optThe option buffer space where delta and length are written.
maxlenThe maximum length of opt.
deltaThe actual delta value to encode.
lengthThe actual length value to encode.
Returns
The number of bytes used or 0 on error.

Definition at line 289 of file option.c.

+ Here is the caller graph for this function:

◆ coap_opt_value()

const uint8_t* coap_opt_value ( const coap_opt_t opt)

Returns a pointer to the value of the given option.

opt must point to an option jump or the beginning of the option. This function returns NULL if opt is not a valid option.

Parameters
optThe option whose value should be returned.
Returns
A pointer to the option value or NULL on error.

Definition at line 246 of file option.c.

+ Here is the caller graph for this function:

◆ coap_option_filter_clear()

void coap_option_filter_clear ( coap_opt_filter_t filter)

Clears filter filter.

Parameters
filterThe filter to clear.

Definition at line 486 of file option.c.

+ Here is the caller graph for this function:

◆ coap_option_filter_get()

int coap_option_filter_get ( coap_opt_filter_t filter,
coap_option_num_t  number 
)

Checks if number is contained in filter.

This function returns 1 if found, 0 if not, or -1 on error (i.e. when the given number does not fit in the filter).

Parameters
filterThe filter object to search.
numberThe option number to search for.
Returns
1 if number was found, 0 otherwise, or -1 on error.

Definition at line 501 of file option.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_option_filter_set()

int coap_option_filter_set ( coap_opt_filter_t filter,
coap_option_num_t  number 
)

Sets the corresponding entry for number in filter.

This function returns 1 if bit was set or 0 on error (i.e. when the given number does not fit in the filter).

Parameters
filterThe filter object to change.
numberThe option number for which the bit should be set.
Returns
1 if bit was set, 0 otherwise.

Definition at line 491 of file option.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_option_filter_unset()

int coap_option_filter_unset ( coap_opt_filter_t filter,
coap_option_num_t  number 
)

Clears the corresponding entry for number in filter.

This function returns 1 if bit was set or 0 on error (i.e. when the given number does not fit in the filter).

Parameters
filterThe filter object to change.
numberThe option number that should be cleared from the filter.
Returns
1 if bit was set, 0 otherwise.

Definition at line 496 of file option.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_option_iterator_init()

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 oi to point to the beginning of the pdu's option list.

This function returns oi on success, 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.

Parameters
pduThe PDU the options of which should be walked through.
oiAn iterator object that will be initilized.
filterAn optional option number filter. With number != COAP_OPT_ALL, coap_option_next() will return only options matching this bitmask. Fence-post options 14, 28, 42, ... are always skipped.
Returns
The iterator object oi on success, NULL otherwise.

Definition at line 110 of file option.c.

+ Here is the caller graph for this function:

◆ coap_option_next()

coap_opt_t* coap_option_next ( coap_opt_iterator_t oi)

Updates the iterator oi to point to the next option.

This function returns a pointer to that option or NULL if no more options exist. The contents of oi will be updated. In particular, oi->n specifies the current option's ordinal number (counted from 1), oi->number is the option's number value, and oi->option points to the beginning of the current option itself. When * advanced past the last option, oi->option will be NULL.

Note that options are skipped whose corresponding bits in the filter specified with coap_option_iterator_init() are 0. Options with numbers that do not fit in this filter hence will always be returned.

Parameters
oiThe option iterator to update.
Returns
The next option or NULL if no more options exist.

Definition at line 146 of file option.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function: