Option Filters

API functions for access option filters. More...

## Data Structures

struct | coap_opt_iterator_t
| Iterator to run through PDU options. 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_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 uint16_t | coap_opt_filter_t[COAP_OPT_FILTER_SIZE]
| Fixed-size vector we use for option filtering. More...

## Functions

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_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 (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_t * | coap_opt_value (const coap_opt_t *opt)
| Returns a pointer to the value of the given option. 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 122 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 84 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 76 of file option.h.

## COAP_OPT_FILTER_SIZE

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

Definition at line 93 of file option.h.

## Typedef Documentation

## coap_opt_filter_t

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

struct {
uint16_t mask;
uint16_t long_opts[COAP_OPT_FILTER_LONG];
uint8_t short_opts[COAP_OPT_FILTER_SHORT];
}
COAP_OPT_FILTER_SHORT
#define COAP_OPT_FILTER_SHORT
The number of option types below 256 that can be stored in an option filter.
Definition: option.h:76
COAP_OPT_FILTER_LONG
#define COAP_OPT_FILTER_LONG
The number of option types above 255 that can be stored in an option filter.
Definition: option.h:84
uint8_t
unsigned char uint8_t
Definition: uthash.h:79

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.

Definition at line 119 of file option.h.

## Function Documentation

## coap_check_option()

coap_opt_t* coap_check_option | ( | coap_pdu_t * | pdu,
|  | uint16_t | type,
|  | coap_opt_iterator_t * | oi
| ) |  |

Retrieves the first option of type `type` from `pdu`.

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

Parameters

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

Returns
  A pointer to the first option of type `type`, 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_opt_delta()

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 `0` on error. The caller of this function must ensure that it does not read over the boundaries of `opt` (e.g. by calling coap_opt_check_delta().

Parameters

  opt | The option to examine.

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

Definition at line 209 of file 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 398 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

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

Returns
  The number of bytes required to encode this option.

Definition at line 377 of file option.c.

Here is the caller graph for this function:

## coap_opt_length()

uint16_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 238 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

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

  opt | The option whose value should be returned.

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

Definition at line 275 of file option.c.

Here is the caller graph for this function:

## coap_option_clrb()

COAP_STATIC_INLINE int coap_option_clrb | ( | coap_opt_filter_t | filter,
|  | uint16_t | type
| ) |  |

Clears the corresponding bit for `type` in `filter`.

This function returns `1` if bit was cleared or `-1` on error (i.e. when the given type does not fit in the filter).

Deprecated:
  Use coap_option_filter_unset() instead.

Parameters

  filter | The filter object to change.
  type | The type for which the bit should be cleared.

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

Definition at line 200 of file option.h.

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

## coap_option_filter_clear()

COAP_STATIC_INLINE void coap_option_filter_clear | ( | coap_opt_filter_t | f | ) |

Clears filter `f`.

Parameters

  f | The filter to clear.

Definition at line 130 of file option.h.

Here is the caller graph for this function:

## coap_option_filter_get()

int coap_option_filter_get | ( | coap_opt_filter_t | filter,
|  | uint16_t | type
| ) |  |

Checks if `type` is contained in `filter`.

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

Parameters

  filter | The filter object to search.
  type | The type to search for.

Returns
  `1` if `type` was found, `0` otherwise, or `-1` on error.

Definition at line 533 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,
|  | uint16_t | type
| ) |  |

Sets the corresponding entry for `type` in `filter`.

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

Parameters

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

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

Definition at line 523 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,
|  | uint16_t | type
| ) |  |

Clears the corresponding entry for `type` in `filter`.

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

Parameters

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

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

Definition at line 528 of file option.c.

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

## coap_option_getb()

COAP_STATIC_INLINE int coap_option_getb | ( | coap_opt_filter_t | filter,
|  | uint16_t | type
| ) |  |

Gets the corresponding bit for `type` in `filter`.

This function returns `1` if the bit is set `0` if not, or `-1` on error (i.e. when the given type does not fit in the filter).

Deprecated:
  Use coap_option_filter_get() instead.

Parameters

  filter | The filter object to read bit from.
  type | The type for which the bit should be read.

Returns
  `1` if bit was set, `0` if not, `-1` on error.

Definition at line 217 of file option.h.

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

  pdu | The PDU the options of which should be walked through.
  oi | An iterator object that will be initilized.
  filter | An optional option type filter. With `type` != `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->type` is the option's type code, 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 type codes 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 146 of file option.c.

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

## coap_option_setb()

COAP_STATIC_INLINE int coap_option_setb | ( | coap_opt_filter_t | filter,
|  | uint16_t | type
| ) |  |

Sets the corresponding bit for `type` in `filter`.

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

Deprecated:
  Use coap_option_filter_set() instead.

Parameters

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

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

Definition at line 183 of file option.h.

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