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

## Macros

#define | PCHAR(p) ((coap_opt_t *)(p))
#define | COAP_OPT_SIZE(opt) coap_opt_size(opt)
#define | options_next(opt)
| Interprets `opt` as pointer to a CoAP option and advances to the next byte past this option. More...
#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...
#define | COAP_OPT_DELTA(opt) coap_opt_delta(opt)
#define | COAP_OPT_SETDELTA(opt, val) coap_opt_encode((opt), COAP_MAX_PDU_SIZE, (val), NULL, 0)
#define | COAP_OPT_LENGTH(opt) coap_opt_length(opt)
#define | COAP_OPT_VALUE(opt) coap_opt_value((coap_opt_t *)opt)

## Typedefs

typedef unsigned char | 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...

## 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_opt_t * | options_start (coap_pdu_t *pdu)
| Calculates the beginning of the PDU's option section. More...
static void | coap_option_filter_clear (coap_opt_filter_t f)
| Clears filter `f`. More...
int | coap_option_filter_set (coap_opt_filter_t filter, unsigned short type)
| Sets the corresponding entry for `type` in `filter`. More...
int | coap_option_filter_unset (coap_opt_filter_t filter, unsigned short type)
| Clears the corresponding entry for `type` in `filter`. More...
int | coap_option_filter_get (const coap_opt_filter_t filter, unsigned short type)
| Checks if `type` is contained in `filter`. More...
static int | coap_option_setb (coap_opt_filter_t filter, unsigned short type)
| Sets the corresponding bit for `type` in `filter`. More...
static int | coap_option_clrb (coap_opt_filter_t filter, unsigned short type)
| Clears the corresponding bit for `type` in `filter`. More...
static int | coap_option_getb (const coap_opt_filter_t filter, unsigned short type)
| Gets the corresponding bit for `type` in `filter`. More...
coap_opt_iterator_t * | coap_option_iterator_init (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, unsigned short 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, unsigned short delta, size_t length)
| Encodes the given delta and length values into `opt`. More...
size_t | coap_opt_encode (coap_opt_t *opt, size_t n, unsigned short delta, const unsigned char *val, size_t length)
| Encodes option with given `delta` into `opt`. More...
unsigned short | coap_opt_delta (const coap_opt_t *opt)
| Decodes the delta value of the next option. More...
unsigned short | coap_opt_length (const coap_opt_t *opt)
| Returns the length of the given option. More...
unsigned char * | coap_opt_value (coap_opt_t *opt)
| Returns a pointer to the value of the given option. More...

## Detailed Description

Helpers for handling options in CoAP PDUs.

Definition in file option.h.

## Macro Definition Documentation

## COAP_OPT_SIZE

#define COAP_OPT_SIZE | ( |  | opt | ) | coap_opt_size(opt)

Deprecated:
  { Use coap_opt_size() instead.

}

Definition at line 63 of file option.h.

## options_next

#define options_next | ( |  | opt | ) |

Interprets `opt` as pointer to a CoAP option and advances to the next byte past this option.

Definition at line 78 of file option.h.

## PCHAR

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

Definition at line 26 of file option.h.

## Typedef Documentation

## coap_opt_t

typedef unsigned char 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.

## Function Documentation

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

  opt | The beginning of the option to parse.
  length | The maximum length of `opt`.
  result | A 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 39 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

  opt | An 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:

## options_start()

coap_opt_t* options_start | ( | coap_pdu_t * | pdu | ) |

Calculates the beginning of the PDU's option section.

Parameters

  pdu | The PDU containing the options.

Returns
  A pointer to the first option if available, or `NULL` otherwise.

Definition at line 25 of file option.c.