libcoap  4.1.1
 All Data Structures Files Functions Variables Typedefs Macros Groups Pages
Data Structures | Macros | Typedefs | Functions
Option Filters

Data Structures

struct  coap_opt_iterator_t
 Iterator to run through PDU options. More...
 

Macros

#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_filter_t [(COAP_MAX_OPT >> 3)+1]
 Fixed-size bit-vector we use for option filtering. More...
 

Functions

static void coap_option_filter_clear (coap_opt_filter_t f)
 Clears filter f. 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_tcoap_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_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, unsigned char 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

Macro Definition Documentation

#define COAP_OPT_ALL   NULL

Pre-defined filter that includes all options.

Definition at line 96 of file option.h.

#define COAP_OPT_DELTA (   opt)    coap_opt_delta(opt)
Deprecated:
{ Use coap_opt_delta() instead. }

Definition at line 283 of file option.h.

#define COAP_OPT_LENGTH (   opt)    coap_opt_length(opt)
Deprecated:
{ Use coap_opt_length() instead. }

Definition at line 305 of file option.h.

#define COAP_OPT_SETDELTA (   opt,
  val 
)    coap_opt_encode((opt), COAP_MAX_PDU_SIZE, (val), NULL, 0)
Deprecated:
{ Use coap_opt_encode() instead. }

Definition at line 286 of file option.h.

#define COAP_OPT_VALUE (   opt)    coap_opt_value((coap_opt_t *)opt)
Deprecated:
{ Use coap_opt_value() instead. }

Definition at line 318 of file option.h.

Typedef Documentation

typedef unsigned char coap_opt_filter_t[(COAP_MAX_OPT >> 3)+1]

Fixed-size bit-vector we use for option filtering.

It is large enough to hold the highest option number known at build time (20 in the core spec).

Definition at line 93 of file option.h.

Function Documentation

coap_opt_t* coap_check_option ( coap_pdu_t pdu,
unsigned char  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
pduThe PDU to parse for options.
typeThe option type code to search for.
oiAn iterator object to use.
Returns
A pointer to the first option of type type, or NULL if not found.

Definition at line 207 of file option.c.

unsigned short 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
optThe option to examine
Returns
The number of bytes read or 0 on error.

Definition at line 220 of file option.c.

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.

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

unsigned short 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 249 of file option.c.

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.

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

unsigned char* coap_opt_value ( 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 284 of file option.c.

static int coap_option_clrb ( coap_opt_filter_t  filter,
unsigned short  type 
)
inlinestatic

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

Parameters
filterThe filter object to change.
typeThe type for which the bit should be cleared.
Returns
1 if bit was set, -1 otherwise.

Definition at line 134 of file option.h.

static void coap_option_filter_clear ( coap_opt_filter_t  f)
inlinestatic

Clears filter f.

Parameters
fThe filter to clear.

Definition at line 104 of file option.h.

static int coap_option_getb ( const coap_opt_filter_t  filter,
unsigned short  type 
)
inlinestatic

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

Parameters
filterThe filter object to read bit from..
typeThe type for which the bit should be read.
Returns
1 if bit was set, 0 if not, -1 on error.

Definition at line 149 of file option.h.

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.

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

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
oiThe option iterator to update.
Returns
The next option or NULL if no more options exist.

Definition at line 157 of file option.c.

static int coap_option_setb ( coap_opt_filter_t  filter,
unsigned short  type 
)
inlinestatic

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

Parameters
filterThe filter object to change.
typeThe type for which the bit should be set.
Returns
1 if bit was set, -1 otherwise.

Definition at line 119 of file option.h.