1COAP_PDU_ACCESS(3)              libcoap Manual              COAP_PDU_ACCESS(3)
2
3
4

NAME

6       coap_pdu_access, coap_check_option, coap_decode_var_bytes,
7       coap_decode_var_bytes8, coap_get_data, coap_opt_length, coap_opt_value,
8       coap_option_filter_clear, coap_option_filter_get - Accessing CoAP PDUs
9

SYNOPSIS

11       #include <coap3/coap.h>
12
13       coap_opt_t *coap_check_option(const coap_pdu_t *pdu, coap_option_num_t
14       number, coap_opt_iterator_t *oi);
15
16       unsigned int coap_decode_var_bytes(const uint8_t *buf, size_t length);
17
18       uint64_t coap_decode_var_bytes8(const uint8_t *buf, size_t length);
19
20       int coap_get_data(const coap_pdu_t *pdu, size_t *length, const uint8_t
21       **_data);
22
23       uint32_t coap_opt_length(const coap_opt_t *opt);
24
25       const uint8_t *coap_opt_value(const coap_opt_t *opt);
26
27       void coap_option_filter_clear(coap_opt_filter_t *filter);
28
29       int coap_option_filter_get(coap_opt_filter_t *filter, coap_option_num_t
30       number);
31
32       int coap_option_filter_set(coap_opt_filter_t *filter, coap_option_num_t
33       number);
34
35       int coap_option_filter_unset(coap_opt_filter_t *filter,
36       coap_option_num_t number);
37
38       coap_opt_iterator_t *coap_option_iterator_init(const coap_pdu_t *pdu,
39       coap_opt_iterator_t *oi, const coap_opt_filter_t *filter);
40
41       coap_opt_t *coap_option_next(coap_opt_iterator_t *oi);
42
43       coap_pdu_code_t coap_pdu_get_code(const coap_pdu_t *pdu);
44
45       coap_mid_t coap_pdu_get_mid(const coap_pdu_t *pdu);
46
47       coap_bin_const_t coap_pdu_get_token(const coap_pdu_t *pdu);
48
49       coap_pdu_type_t coap_pdu_get_type(const coap_pdu_t *pdu);
50
51       For specific (D)TLS library support, link with -lcoap-3-notls,
52       -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or
53       -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default
54       (D)TLS library support.
55

DESCRIPTION

57       The CoAP PDU is of the form
58
59       --header--|--optional token--|--optional options--|--optional payload--
60
61       The terminology used is taken mainly from
62       https://tools.ietf.org/html/rfc7252#section-1.2
63
64       The following functions provide access to the information held within a
65       PDU.
66
67       Header:
68
69       The coap_pdu_get_type() function returns one of the messages types
70       below from the PDU pdu.
71
72           COAP_MESSAGE_CON  Type confirmable.
73           COAP_MESSAGE_NON  Type non-confirmable.
74           COAP_MESSAGE_ACK  Type acknowledge
75           COAP_MESSAGE_RST  Type reset.
76
77       The coap_pdu_get_code() function returns one of the codes below from
78       the PDU pdu. It is possible that new codes are added in over time.
79
80           COAP_EMPTY_CODE                               0.00
81           COAP_REQUEST_CODE_GET                         0.01
82           COAP_REQUEST_CODE_POST                        0.02
83           COAP_REQUEST_CODE_PUT                         0.03
84           COAP_REQUEST_CODE_DELETE                      0.04
85           COAP_REQUEST_CODE_FETCH                       0.05
86           COAP_REQUEST_CODE_PATCH                       0.06
87           COAP_REQUEST_CODE_IPATCH                      0.07
88           COAP_RESPONSE_CODE_OK                         2.00
89           COAP_RESPONSE_CODE_CREATED                    2.01
90           COAP_RESPONSE_CODE_DELETED                    2.02
91           COAP_RESPONSE_CODE_VALID                      2.03
92           COAP_RESPONSE_CODE_CHANGED                    2.04
93           COAP_RESPONSE_CODE_CONTENT                    2.05
94           COAP_RESPONSE_CODE_CONTINUE                   2.31
95           COAP_RESPONSE_CODE_BAD_REQUEST                4.00
96           COAP_RESPONSE_CODE_UNAUTHORIZED               4.01
97           COAP_RESPONSE_CODE_BAD_OPTION                 4.02
98           COAP_RESPONSE_CODE_FORBIDDEN                  4.03
99           COAP_RESPONSE_CODE_NOT_FOUND                  4.04
100           COAP_RESPONSE_CODE_NOT_ALLOWED                4.05
101           COAP_RESPONSE_CODE_NOT_ACCEPTABLE             4.06
102           COAP_RESPONSE_CODE_INCOMPLETE                 4.08
103           COAP_RESPONSE_CODE_CONFLICT                   4.09
104           COAP_RESPONSE_CODE_PRECONDITION_FAILED        4.12
105           COAP_RESPONSE_CODE_REQUEST_TOO_LARGE          4.13
106           COAP_RESPONSE_CODE_UNSUPPORTED_CONTENT_FORMAT 4.15
107           COAP_RESPONSE_CODE_UNPROCESSABLE              4.22
108           COAP_RESPONSE_CODE_TOO_MANY_REQUESTS          4.29
109           COAP_RESPONSE_CODE_INTERNAL_ERROR             5.00
110           COAP_RESPONSE_CODE_NOT_IMPLEMENTED            5.01
111           COAP_RESPONSE_CODE_BAD_GATEWAY                5.02
112           COAP_RESPONSE_CODE_SERVICE_UNAVAILABLE        5.03
113           COAP_RESPONSE_CODE_GATEWAY_TIMEOUT            5.04
114           COAP_RESPONSE_CODE_PROXYING_NOT_SUPPORTED     5.05
115           COAP_RESPONSE_CODE_HOP_LIMIT_REACHED          5.08
116           COAP_SIGNALING_CODE_CSM                       7.01
117           COAP_SIGNALING_CODE_PING                      7.02
118           COAP_SIGNALING_CODE_PONG                      7.03
119           COAP_SIGNALING_CODE_RELEASE                   7.04
120           COAP_SIGNALING_CODE_ABORT                     7.05
121
122       The coap_pdu_get_mid() returns the message id from the PDU pdu.
123
124       Token:
125
126       The coap_pdu_get_token() returns the token information held in the PDU
127       pdu which may be zero length.
128
129       Options:
130
131       The following is the current list of options with their numeric value
132
133           /*
134            * The C, U, and N flags indicate the properties
135            * Critical, Unsafe, and NoCacheKey, respectively.
136            * If U is set, then N has no meaning as per
137            * https://tools.ietf.org/html/rfc7252#section-5.10
138            * and is set to a -.
139            * Separately, R is for the options that can be repeated
140            *
141            * The least significant byte of the option is set as followed
142            * as per https://tools.ietf.org/html/rfc7252#section-5.4.6
143            *
144            *   0   1   2   3   4   5   6   7
145            * --+---+---+---+---+---+---+---+
146            *           | NoCacheKey| U | C |
147            * --+---+---+---+---+---+---+---+
148            *
149            * https://tools.ietf.org/html/rfc8613#section-4 goes on to define E, I and U
150            * properties Encrypted and Integrity Protected, Integrity Protected Only and
151            * Unprotected respectively.  Integrity Protected Only is not currently used.
152            *
153            * An Option is tagged with CUNREIU with any of the letters replaced with _ if
154            * not set, or - for N if U is set (see above) for aiding understanding of the
155            * Option.
156            */
157
158           COAP_OPTION_IF_MATCH        1 /* C__RE__, opaque,    0-8 B, RFC7252 */
159           COAP_OPTION_URI_HOST        3 /* CU-___U, String,  1-255 B, RFC7252 */
160           COAP_OPTION_ETAG            4 /* ___RE__, opaque,    1-8 B, RFC7252 */
161           COAP_OPTION_IF_NONE_MATCH   5 /* C___E__, empty,       0 B, RFC7252 */
162           COAP_OPTION_OBSERVE         6 /* _U-_E_U, empty/uint,  0 B/0-3 B, RFC7641 */
163           COAP_OPTION_URI_PORT        7 /* CU-___U, uint,      0-2 B, RFC7252 */
164           COAP_OPTION_LOCATION_PATH   8 /* ___RE__, String,  0-255 B, RFC7252 */
165           COAP_OPTION_OSCORE          9 /* C_____U, *,       0-255 B, RFC8613 */
166           COAP_OPTION_URI_PATH       11 /* CU-RE__, String,  0-255 B, RFC7252 */
167           COAP_OPTION_CONTENT_FORMAT 12 /* ____E__, uint,      0-2 B, RFC7252 */
168           /* COAP_OPTION_MAXAGE default 60 seconds if not set */
169           COAP_OPTION_MAXAGE         14 /* _U-_E_U, uint,      0-4 B, RFC7252 */
170           COAP_OPTION_URI_QUERY      15 /* CU-RE__, String,  1-255 B, RFC7252 */
171           COAP_OPTION_HOP_LIMIT      16 /* ______U, uint,        1 B, RFC8768 */
172           COAP_OPTION_ACCEPT         17 /* C___E__, uint,      0-2 B, RFC7252 */
173           COAP_OPTION_LOCATION_QUERY 20 /* ___RE__, String,  0-255 B, RFC7252 */
174           COAP_OPTION_BLOCK2         23 /* CU-_E_U, uint,      0-3 B, RFC7959 */
175           COAP_OPTION_BLOCK1         27 /* CU-_E_U, uint,      0-3 B, RFC7959 */
176           COAP_OPTION_SIZE2          28 /* __N_E_U, uint,      0-4 B, RFC7959 */
177           COAP_OPTION_PROXY_URI      35 /* CU-___U, String, 1-1034 B, RFC7252 */
178           COAP_OPTION_PROXY_SCHEME   39 /* CU-___U, String,  1-255 B, RFC7252 */
179           COAP_OPTION_SIZE1          60 /* __N_E_U, uint,      0-4 B, RFC7252 */
180           COAP_OPTION_NORESPONSE    258 /* _U-_E_U, uint,      0-1 B, RFC7967 */
181
182       See FURTHER INFORMATION as to how to get the latest list.
183
184       The coap_check_option() function is used to check whether the specified
185       option number is in the PDU pdu. The option iterator oi is used as an
186       internal storage location while iterating through the options looking
187       for the specific number. If the number is repeated in the pdu, only the
188       first occurrence will be returned. If the option is not found, NULL is
189       returned.
190
191       Alternatively, the coap_option_iterator_init() function can be used to
192       initialize option iterator oi, applying a filter filter to indicate
193       which options are to be ignored when iterating through the options. The
194       filter can be NULL (or COAP_OPT_ALL) if all of the options are
195       required. Then this is followed by using the coap_option_next()
196       function in a loop to return all the appropriate options until NULL is
197       returned - indicating the end of available the options. See EXAMPLES
198       below for further information.
199
200       To set up the filter, the following 4 functions are available.
201
202       The coap_option_filter_clear() function initializes filter to have no
203       options set.
204
205       The coap_option_filter_get() function is used to check whether option
206       number is set in filter.
207
208       The coap_option_filter_set() function is used to set option number in
209       filter.
210
211       The coap_option_filter_unset() function is used to remove option number
212       in filter.
213
214       The coap_opt_length() function returns the length of the option opt.
215
216       The coap_opt_val() function returns a pointer to the start of the data
217       for the option.
218
219       The coap_decode_var_bytes() function will decode an option up to 4
220       bytes long from buf and length into an unsigned 32bit number.
221
222       The *coap_decode_var_bytes*8() function will decode an option up to 8
223       bytes long from buf and length into an unsigned 64bit number.
224
225       Payload:
226
227       The coap_get_data() function is used abstract from the pdu information
228       about the received data by updating length with the length of data
229       available, and data with a pointer to where the data is located.
230
231       NOTE: This function has been updated by coap_get_data_large() when
232       large transfers may take place. See coap_block(3).
233

EXAMPLES

235       Abstract information from PDU
236
237           #include <coap3/coap.h>
238
239           static void
240           get_pdu_information(coap_pdu_t *pdu) {
241
242             int ret;
243             /* Header variables */
244             coap_pdu_type_t pdu_type;
245             coap_pdu_code_t pdu_code;
246             coap_mid_t pdu_mid;
247             /* Token variables */
248             coap_bin_const_t pdu_token;
249             /* Option variables */
250             coap_opt_iterator_t opt_iter;
251             coap_opt_t *option;
252             coap_opt_filter_t ignore_options;
253
254             /* Data payload variables */
255             size_t pdu_data_length;
256             const uint8_t *pdu_data;
257             size_t pdu_data_offset;
258             size_t pdu_data_total_length;
259
260             /* Pull in the header information */
261             pdu_type = coap_pdu_get_type(pdu);
262             pdu_code = coap_pdu_get_code(pdu);
263             pdu_mid = coap_pdu_get_mid(pdu);
264
265             /* Pull in the token information */
266             pdu_token = coap_pdu_get_token(pdu);
267
268             /* Pull in the option information */
269             /* Specific option check */
270             option = coap_check_option(pdu, COAP_OPTION_OBSERVE, &opt_iter);
271             if (option) {
272               uint32_t value = coap_decode_var_bytes(coap_opt_value(option),
273                                                      coap_opt_length(option));
274               coap_log(LOG_INFO, "Option OBSERVE, value %u\n", value);
275             }
276             /* Iterate through all options */
277             coap_option_iterator_init(pdu, &opt_iter, COAP_OPT_ALL);
278             while ((option = coap_option_next(&opt_iter))) {
279               coap_log(LOG_INFO, "A: Option %d, Length %u\n",
280                        opt_iter.number, coap_opt_length(option));
281             }
282             /* Iterate through options, some ignored */
283             coap_option_filter_clear(&ignore_options);
284             coap_option_filter_set(&ignore_options, COAP_OPTION_OBSERVE);
285             coap_option_iterator_init(pdu, &opt_iter, &ignore_options);
286             while ((option = coap_option_next(&opt_iter))) {
287               coap_log(LOG_INFO, "I: Option %d, Length %u\n",
288                        opt_iter.number, coap_opt_length(option));
289             }
290
291             /* Pull in the payload information */
292             ret = coap_get_data(pdu, &pdu_data_length, &pdu_data);
293               /* or */
294             ret = coap_get_data_large(pdu, &pdu_data_length, &pdu_data,
295                                       &pdu_data_offset, &pdu_data_total_length);
296
297           }
298

SEE ALSO

300       coap_block(3) and coap_pdu_setup(3)
301

FURTHER INFORMATION

303       See
304
305       "RFC7252: The Constrained Application Protocol (CoAP)"
306
307       "RFC8613: Object Security for Constrained RESTful Environments
308       (OSCORE)"
309
310       for further information.
311
312       See
313       https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#option-numbers
314       for the current set of defined CoAP Options.
315

BUGS

317       Please report bugs on the mailing list for libcoap:
318       libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
319       https://github.com/obgm/libcoap/issues
320

AUTHORS

322       The libcoap project <libcoap-developers@lists.sourceforge.net>
323
324
325
326coap_pdu_access 4.3.0             01/20/2022                COAP_PDU_ACCESS(3)
Impressum