libcoap 4.3.2rc2

Data Structures | Macros | Typedefs | Functions
Option Filters
Application API

API 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_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. More...
coap_opt_t * | coap_option_next (coap_opt_iterator_t *oi)
| Updates the iterator `oi` to point to the next option. More...
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`. 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_t * | coap_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 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 108 of file coap_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 86 of file coap_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 78 of file coap_option.h.

## Typedef Documentation

## ◆ coap_opt_filter_t

typedef struct coap_opt_filter_t coap_opt_filter_t

## ◆ coap_optlist_t

typedef struct coap_optlist_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_OBSERVE_ESTABLISH, NULL));
coap_add_optlist_pdu(pdu, &optlist_chain);
... other code ...
coap_delete_optlist(optlist_chain);
COAP_OBSERVE_ESTABLISH
#define COAP_OBSERVE_ESTABLISH
The value COAP_OBSERVE_ESTABLISH in a GET/FETCH request option COAP_OPTION_OBSERVE indicates a new ob...
Definition: coap_subscribe.h:33
coap_new_optlist
coap_optlist_t * coap_new_optlist(uint16_t number, size_t length, const uint8_t *data)
Create a new optlist entry.
Definition: coap_option.c:511
coap_add_optlist_pdu
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: coap_option.c:551
coap_new_pdu
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: coap_pdu.c:153
COAP_OPTION_OBSERVE
#define COAP_OPTION_OBSERVE
Definition: coap_pdu.h:119
coap_optlist_t
Representation of chained list of CoAP options to install.
Definition: coap_option.h:325
coap_pdu_t
structure for CoAP PDUs
Definition: coap_pdu_internal.h:119

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

  pdu | The pdu to add the options to from the chain list
  optlist_chain | The chained list of optlist to add to the pdu

Returns
  `1` if succesful or `0` if failure;

Definition at line 551 of file coap_option.c.

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

  pdu | The PDU to parse for options.
  number | The option number to search for.
  oi | An iterator object to use.

Returns
  A pointer to the first option of number `number`, or `NULL` if not found.

Definition at line 199 of file coap_option.c.

## ◆ 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_chain | The optlist chain to remove all the entries from

Definition at line 592 of file coap_option.c.

## ◆ 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_chain | The chain to add optlist to
  optlist | The optlist to add to the queue

Returns
  `1` if successful, `0` otherwise.

Definition at line 571 of file coap_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

  number | The option number (COAP_OPTION_*)
  length | The option length
  data | The option value data

Returns
  A pointer to the new optlist entry, or `NULL` if error

Definition at line 511 of file coap_option.c.

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

  opt | The option buffer space where `val` is written.
  n | Maximum length of `opt`.
  delta | The option delta.
  val | The option value to copy into `opt`.
  length | The 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 372 of file coap_option.c.

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

  delta | The option delta.
  length | The option length.

Returns
  The number of bytes required to encode this option.

Definition at line 351 of file coap_option.c.

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

  opt | The option whose length should be returned.

Returns
  The option's length or `0` when undefined.

Definition at line 212 of file coap_option.c.

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

  opt | The option buffer space where `delta` and `length` are written.
  maxlen | The maximum length of `opt`.
  delta | The actual delta value to encode.
  length | The actual length value to encode.

Returns
  The number of bytes used or `0` on error.

Definition at line 292 of file coap_option.c.

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

  opt | The option whose value should be returned.

Returns
  A pointer to the option value or `NULL` on error.

Definition at line 249 of file coap_option.c.

## ◆ coap_option_filter_clear()

void coap_option_filter_clear | ( | coap_opt_filter_t * | filter | ) |

Clears filter `filter`.

Parameters

  filter | The filter to clear.

Definition at line 491 of file coap_option.c.

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

Parameters

  filter | The filter object to search.
  number | The option number to search for.

Returns
  `1` if `number` was found, `0` otherwise

Definition at line 506 of file coap_option.c.

## ◆ 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 there is not enough space to fit the given number in the filter).

Parameters

  filter | The filter object to change.
  number | The option number for which the bit should be set.

Returns
  `1` if bit was set, `0` otherwise.

Definition at line 496 of file coap_option.c.

## ◆ 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` if not previously set.

Parameters

  filter | The filter object to change.
  number | The option number that should be cleared from the filter.

Returns
  `1` if bit was cleared, `0` otherwise.

Definition at line 501 of file coap_option.c.

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

  pdu | The PDU the options of which should be walked through.
  oi | An iterator object that will be initilized.
  filter | An 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 117 of file coap_option.c.

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

  oi | The option iterator to update.

Returns
  The next option or `NULL` if no more options exist.

Definition at line 153 of file coap_option.c.