libcoap 4.3.2rc2

coap_option.h
Go to the documentation of this file.
1/*
2 * coap_option.h -- helpers for handling options in CoAP PDUs
3 *
4 * Copyright (C) 2010-2013,2022-2023 Olaf Bergmann <bergmann@tzi.org>
5 *
6 * SPDX-License-Identifier: BSD-2-Clause
7 *
8 * This file is part of the CoAP library libcoap. Please see README for terms
9 * of use.
10 */
11
17#ifndef COAP_OPTION_H_
18#define COAP_OPTION_H_
19
20 typedef uint16_t coap_option_num_t;
21
26 typedef uint8_t coap_opt_t;
27#define PCHAR(p) ((coap_opt_t *)(p))
28
32 typedef struct {
33 uint16_t delta;
34 size_t length;
35 const uint8_t *value;
36} coap_option_t;
37
50 size_t coap_opt_parse(const coap_opt_t *opt,
51 size_t length,
52 coap_option_t *result);
53
63 size_t coap_opt_size(const coap_opt_t *opt);
64
78#define COAP_OPT_FILTER_SHORT 6
79
86#define COAP_OPT_FILTER_LONG 2
87
88/* Ensure that COAP_OPT_FILTER_SHORT and COAP_OPT_FILTER_LONG are set
89 * correctly. */
90#if (COAP_OPT_FILTER_SHORT + COAP_OPT_FILTER_LONG > 16)
91#error COAP_OPT_FILTER_SHORT + COAP_OPT_FILTER_LONG must be less or equal 16
92#endif /* (COAP_OPT_FILTER_SHORT + COAP_OPT_FILTER_LONG > 16) */
93
94/*
95 * mask contains a bit vector that indicates which fields in the long_opts[]
96 * and subsequent short_opts[] are used. The first COAP_OPT_FILTER_LONG bits
97 * correspond to the long option types that are stored in long_opts[]
98 * elements. The next COAP_OPT_FILTER_SHORT bits correspond to the short
99 * option types that are stored in short_opts[].
100 */
101 typedef struct coap_opt_filter_t {
102 uint16_t mask;
103 uint16_t long_opts[COAP_OPT_FILTER_LONG];
104 uint8_t short_opts[COAP_OPT_FILTER_SHORT];
105} coap_opt_filter_t;
106
108#define COAP_OPT_ALL NULL
109
115 void coap_option_filter_clear(coap_opt_filter_t *filter);
116
127 int coap_option_filter_set(coap_opt_filter_t *filter, coap_option_num_t number);
128
138 int coap_option_filter_unset(coap_opt_filter_t *filter,
139 coap_option_num_t number);
140
150 int coap_option_filter_get(coap_opt_filter_t *filter, coap_option_num_t number);
151
168 typedef struct {
169 size_t length;
170 coap_option_num_t number;
171 unsigned int bad:1;
172 unsigned int filtered:1;
173 coap_opt_t *next_option;
174 coap_opt_filter_t filter;
175} coap_opt_iterator_t;
176
193 coap_opt_iterator_t *coap_option_iterator_init(const coap_pdu_t *pdu,
194 coap_opt_iterator_t *oi,
195 const coap_opt_filter_t *filter);
196
213 coap_opt_t *coap_option_next(coap_opt_iterator_t *oi);
214
228 coap_opt_t *coap_check_option(const coap_pdu_t *pdu,
229 coap_option_num_t number,
230 coap_opt_iterator_t *oi);
231
246 size_t coap_opt_setheader(coap_opt_t *opt,
247 size_t maxlen,
248 uint16_t delta,
249 size_t length);
250
260 size_t coap_opt_encode_size(uint16_t delta, size_t length);
261
277 size_t coap_opt_encode(coap_opt_t *opt,
278 size_t n,
279 uint16_t delta,
280 const uint8_t *val,
281 size_t length);
282
296uint32_t coap_opt_length(const coap_opt_t *opt);
297
307 const uint8_t *coap_opt_value(const coap_opt_t *opt);
308
325 typedef struct coap_optlist_t {
326 struct coap_optlist_t *next;
327 uint16_t number;
328 size_t length;
329 uint8_t *data;
330} coap_optlist_t;
331
347 coap_optlist_t *coap_new_optlist(uint16_t number,
348 size_t length,
349 const uint8_t *data);
350
360 int coap_add_optlist_pdu(coap_pdu_t *pdu, coap_optlist_t **optlist_chain);
361
373 int coap_insert_optlist(coap_optlist_t **optlist_chain,
374 coap_optlist_t *optlist);
375
382 void coap_delete_optlist(coap_optlist_t *optlist_chain);
383
398 COAP_STATIC_INLINE COAP_DEPRECATED int
399 coap_option_setb(coap_opt_filter_t *filter, uint16_t type) {
400 return coap_option_filter_set(filter, type) ? 1 : -1;
401}
402
414 COAP_STATIC_INLINE COAP_DEPRECATED int
415 coap_option_clrb(coap_opt_filter_t *filter, uint16_t type) {
416 return coap_option_filter_unset(filter, type) ? 1 : -1;
417}
418
430 COAP_STATIC_INLINE COAP_DEPRECATED int
431 coap_option_getb(coap_opt_filter_t *filter, uint16_t type) {
432 return coap_option_filter_get(filter, type);
433}
434
435#endif /* COAP_OPTION_H_ */
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.
Definition: coap_option.c:41
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.
Definition: coap_option.c:284
coap_option_num_t
uint16_t coap_option_num_t
Definition: coap_option.h:20
coap_opt_t
uint8_t coap_opt_t
Use byte-oriented access methods here because sliding a complex struct coap_opt_t over the data buffe...
Definition: coap_option.h:26
coap_option_clrb
COAP_STATIC_INLINE COAP_DEPRECATED int coap_option_clrb(coap_opt_filter_t *filter, uint16_t type)
Clears the corresponding bit for type in filter.
Definition: coap_option.h:415
coap_option_getb
COAP_STATIC_INLINE COAP_DEPRECATED int coap_option_getb(coap_opt_filter_t *filter, uint16_t type)
Gets the corresponding bit for type in filter.
Definition: coap_option.h:431
coap_option_setb
COAP_STATIC_INLINE COAP_DEPRECATED int coap_option_setb(coap_opt_filter_t *filter, uint16_t type)
Sets the corresponding bit for type in filter.
Definition: coap_option.h:399
coap_option_next
coap_opt_t * coap_option_next(coap_opt_iterator_t *oi)
Updates the iterator oi to point to the next option.
Definition: coap_option.c:153
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_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.
Definition: coap_option.c:372
coap_opt_length
uint32_t coap_opt_length(const coap_opt_t *opt)
Returns the length of the given option.
Definition: coap_option.c:212
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.
Definition: coap_option.c:117
coap_delete_optlist
void coap_delete_optlist(coap_optlist_t *optlist_chain)
Removes all entries from the optlist_chain, freeing off their memory usage.
Definition: coap_option.c:592
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.
Definition: coap_option.c:351
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: coap_option.h:78
coap_opt_filter_t
struct coap_opt_filter_t coap_opt_filter_t
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.
Definition: coap_option.c:501
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 ...
Definition: coap_option.c:551
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: coap_option.h:86
coap_optlist_t
struct coap_optlist_t coap_optlist_t
Representation of chained list of CoAP options to install.
coap_option_filter_clear
void coap_option_filter_clear(coap_opt_filter_t *filter)
Clears filter filter.
Definition: coap_option.c:491
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.
Definition: coap_option.c:199
coap_insert_optlist
int coap_insert_optlist(coap_optlist_t **optlist_chain, coap_optlist_t *optlist)
Adds optlist to the given optlist_chain.
Definition: coap_option.c:571
coap_opt_value
const uint8_t * coap_opt_value(const coap_opt_t *opt)
Returns a pointer to the value of the given option.
Definition: coap_option.c:249
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.
Definition: coap_option.c:506
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.
Definition: coap_option.c:496
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.
Definition: coap_option.c:292
COAP_DEPRECATED
#define COAP_DEPRECATED
Definition: libcoap.h:61
COAP_STATIC_INLINE
#define COAP_STATIC_INLINE
Definition: libcoap.h:53
coap_opt_filter_t
Definition: coap_option.h:101
coap_opt_filter_t::mask
uint16_t mask
Definition: coap_option.h:102
coap_opt_filter_t::short_opts
uint8_t short_opts[COAP_OPT_FILTER_SHORT]
Definition: coap_option.h:104
coap_opt_filter_t::long_opts
uint16_t long_opts[COAP_OPT_FILTER_LONG]
Definition: coap_option.h:103
coap_opt_iterator_t
Iterator to run through PDU options.
Definition: coap_option.h:168
coap_opt_iterator_t::next_option
coap_opt_t * next_option
pointer to the unparsed next option
Definition: coap_option.h:173
coap_opt_iterator_t::filter
coap_opt_filter_t filter
option filter
Definition: coap_option.h:174
coap_opt_iterator_t::bad
unsigned int bad
iterator object is ok if not set
Definition: coap_option.h:171
coap_opt_iterator_t::length
size_t length
remaining length of PDU
Definition: coap_option.h:169
coap_opt_iterator_t::filtered
unsigned int filtered
denotes whether or not filter is used
Definition: coap_option.h:172
coap_opt_iterator_t::number
coap_option_num_t number
decoded option number
Definition: coap_option.h:170
coap_option_t
Representation of CoAP options.
Definition: coap_option.h:32
coap_option_t::value
const uint8_t * value
Definition: coap_option.h:35
coap_option_t::delta
uint16_t delta
Definition: coap_option.h:33
coap_option_t::length
size_t length
Definition: coap_option.h:34
coap_optlist_t
Representation of chained list of CoAP options to install.
Definition: coap_option.h:325
coap_optlist_t::number
uint16_t number
the option number (no delta coding)
Definition: coap_option.h:327
coap_optlist_t::length
size_t length
the option value length
Definition: coap_option.h:328
coap_optlist_t::data
uint8_t * data
the option data
Definition: coap_option.h:329
coap_optlist_t::next
struct coap_optlist_t * next
next entry in the optlist chain
Definition: coap_option.h:326
coap_pdu_t
structure for CoAP PDUs
Definition: coap_pdu_internal.h:119