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,
9       coap_option_filter_set, coap_option_filter_unset,
10       coap_option_iterator_init, coap_option_next, coap_pdu_get_code,
11       coap_pdu_get_mid, coap_pdu_get_token, coap_pdu_get_type,
12       coap_get_uri_path - Accessing CoAP PDUs
13

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUES

245       coap_check_option() and coap_option_next() returns a coap_opt_t* or
246       NULL if not found.
247
248       coap_decode_var_bytes() and coap_decode_var_bytes8() return the decoded
249       value.
250
251       coap_pdu_get_code(), coap_pdu_get_mid(), coap_pdu_get_type() return the
252       appropriate value.
253
254       coap_option_filter_set(), coap_option_filter_set() and
255       coap_option_filter_unset() return 1 on success or 0 on failure.
256
257       coap_get_data() returns 1 if data, else 0.
258
259       coap_opt_length() returns the option length.
260
261       coap_opt_value() returns a pointer to the start of the option value or
262       NULL if error.
263
264       coap_option_iterator_init() returns ap pointer to the provided
265       interator or NULL on error.
266
267       coap_pdu_get_token() returns a pointer to the token in the pdu.
268
269       coap_get_uri_path() returns an allocated pointer to the uri path in the
270       pdu or NULL on error. This pointer will need to be freed off.
271

EXAMPLES

273       Abstract information from PDU
274
275           #include <coap3/coap.h>
276
277           static void
278           get_pdu_information(coap_pdu_t *pdu) {
279
280             int ret;
281             /* Header variables */
282             coap_pdu_type_t pdu_type;
283             coap_pdu_code_t pdu_code;
284             coap_mid_t pdu_mid;
285             /* Token variables */
286             coap_bin_const_t pdu_token;
287             /* Option variables */
288             coap_opt_iterator_t opt_iter;
289             coap_opt_t *option;
290             coap_opt_filter_t ignore_options;
291
292             /* Data payload variables */
293             size_t pdu_data_length;
294             const uint8_t *pdu_data;
295             size_t pdu_data_offset;
296             size_t pdu_data_total_length;
297
298             /* Pull in the header information */
299             pdu_type = coap_pdu_get_type(pdu);
300             pdu_code = coap_pdu_get_code(pdu);
301             pdu_mid = coap_pdu_get_mid(pdu);
302
303             /* Pull in the token information */
304             pdu_token = coap_pdu_get_token(pdu);
305
306             /* Pull in the option information */
307             /* Specific option check */
308             option = coap_check_option(pdu, COAP_OPTION_OBSERVE, &opt_iter);
309             if (option) {
310               uint32_t value = coap_decode_var_bytes(coap_opt_value(option),
311                                                      coap_opt_length(option));
312               coap_log(LOG_INFO, "Option OBSERVE, value %u\n", value);
313             }
314             /* Iterate through all options */
315             coap_option_iterator_init(pdu, &opt_iter, COAP_OPT_ALL);
316             while ((option = coap_option_next(&opt_iter))) {
317               coap_log(LOG_INFO, "A: Option %d, Length %u\n",
318                        opt_iter.number, coap_opt_length(option));
319             }
320             /* Iterate through options, some ignored */
321             coap_option_filter_clear(&ignore_options);
322             coap_option_filter_set(&ignore_options, COAP_OPTION_OBSERVE);
323             coap_option_iterator_init(pdu, &opt_iter, &ignore_options);
324             while ((option = coap_option_next(&opt_iter))) {
325               coap_log(LOG_INFO, "I: Option %d, Length %u\n",
326                        opt_iter.number, coap_opt_length(option));
327             }
328
329             /* Pull in the payload information */
330             ret = coap_get_data(pdu, &pdu_data_length, &pdu_data);
331               /* or */
332             ret = coap_get_data_large(pdu, &pdu_data_length, &pdu_data,
333                                       &pdu_data_offset, &pdu_data_total_length);
334
335           }
336

SEE ALSO

338       coap_block(3) and coap_pdu_setup(3)
339

FURTHER INFORMATION

341       See
342
343       "RFC7252: The Constrained Application Protocol (CoAP)"
344
345       "RFC8613: Object Security for Constrained RESTful Environments
346       (OSCORE)"
347
348       for further information.
349
350       See
351       https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#option-numbers
352       for the current set of defined CoAP Options.
353

BUGS

355       Please report bugs on the mailing list for libcoap:
356       libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
357       https://github.com/obgm/libcoap/issues
358

AUTHORS

360       The libcoap project <libcoap-developers@lists.sourceforge.net>
361
362
363
364coap_pdu_access 4.3.1             11/24/2022                COAP_PDU_ACCESS(3)
Impressum