1COAP_PDU_ACCESS(3) libcoap Manual COAP_PDU_ACCESS(3)
2
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
15 #include <coap3/coap.h>
16 coap_opt_t *coap_check_option(const coap_pdu_t *pdu, coap_option_num_t
18 number, coap_opt_iterator_t *oi);
19 unsigned int coap_decode_var_bytes(const uint8_t *buf, size_t length);
21 uint64_t coap_decode_var_bytes8(const uint8_t *buf, size_t length);
23 int coap_get_data(const coap_pdu_t *pdu, size_t *length, const uint8_t
25 **_data);
26 uint32_t coap_opt_length(const coap_opt_t *opt);
28 const uint8_t *coap_opt_value(const coap_opt_t *opt);
30 void coap_option_filter_clear(coap_opt_filter_t *filter);
32 int coap_option_filter_get(coap_opt_filter_t *filter, coap_option_num_t
34 number);
35 int coap_option_filter_set(coap_opt_filter_t *filter, coap_option_num_t
37 number);
38 int coap_option_filter_unset(coap_opt_filter_t *filter,
40 coap_option_num_t number);
41 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 coap_opt_t *coap_option_next(coap_opt_iterator_t *oi);
46 coap_pdu_code_t coap_pdu_get_code(const coap_pdu_t *pdu);
48 coap_mid_t coap_pdu_get_mid(const coap_pdu_t *pdu);
50 coap_bin_const_t coap_pdu_get_token(const coap_pdu_t *pdu);
52 coap_pdu_type_t coap_pdu_get_type(const coap_pdu_t *pdu);
54 coap_string_t *coap_get_uri_path(const coap_pdu_t *pdu);
56 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
63 The CoAP PDU is of the form
64 --header--|--optional token--|--optional options--|--optional payload--
66 The terminology used is taken mainly from "RFC7252 1.2. Terminology".
68 The following functions provide access to the information held within
70 different parts of a PDU.
71
73 Function: coap_pdu_get_type()
74 The coap_pdu_get_type() function returns one of the messages types
76 below from the PDU pdu header.
77 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 NOTE: For reliable messages RFC8323, this will always return
84 COAP_MESSAGE_CON.
85 Function: coap_pdu_get_code()
87 The coap_pdu_get_code() function returns one of the codes below from
89 the PDU pdu header. It is possible that new codes are added in over
90 time.
91 COAP_EMPTY_CODE 0.00
93 COAP_REQUEST_CODE_GET 0.01
94 COAP_REQUEST_CODE_POST 0.02
95 COAP_REQUEST_CODE_PUT 0.03
96 COAP_REQUEST_CODE_DELETE 0.04
97 COAP_REQUEST_CODE_FETCH 0.05
98 COAP_REQUEST_CODE_PATCH 0.06
99 COAP_REQUEST_CODE_IPATCH 0.07
100 COAP_RESPONSE_CODE_OK 2.00
101 COAP_RESPONSE_CODE_CREATED 2.01
102 COAP_RESPONSE_CODE_DELETED 2.02
103 COAP_RESPONSE_CODE_VALID 2.03
104 COAP_RESPONSE_CODE_CHANGED 2.04
105 COAP_RESPONSE_CODE_CONTENT 2.05
106 COAP_RESPONSE_CODE_CONTINUE 2.31
107 COAP_RESPONSE_CODE_BAD_REQUEST 4.00
108 COAP_RESPONSE_CODE_UNAUTHORIZED 4.01
109 COAP_RESPONSE_CODE_BAD_OPTION 4.02
110 COAP_RESPONSE_CODE_FORBIDDEN 4.03
111 COAP_RESPONSE_CODE_NOT_FOUND 4.04
112 COAP_RESPONSE_CODE_NOT_ALLOWED 4.05
113 COAP_RESPONSE_CODE_NOT_ACCEPTABLE 4.06
114 COAP_RESPONSE_CODE_INCOMPLETE 4.08
115 COAP_RESPONSE_CODE_CONFLICT 4.09
116 COAP_RESPONSE_CODE_PRECONDITION_FAILED 4.12
117 COAP_RESPONSE_CODE_REQUEST_TOO_LARGE 4.13
118 COAP_RESPONSE_CODE_UNSUPPORTED_CONTENT_FORMAT 4.15
119 COAP_RESPONSE_CODE_UNPROCESSABLE 4.22
120 COAP_RESPONSE_CODE_TOO_MANY_REQUESTS 4.29
121 COAP_RESPONSE_CODE_INTERNAL_ERROR 5.00
122 COAP_RESPONSE_CODE_NOT_IMPLEMENTED 5.01
123 COAP_RESPONSE_CODE_BAD_GATEWAY 5.02
124 COAP_RESPONSE_CODE_SERVICE_UNAVAILABLE 5.03
125 COAP_RESPONSE_CODE_GATEWAY_TIMEOUT 5.04
126 COAP_RESPONSE_CODE_PROXYING_NOT_SUPPORTED 5.05
127 COAP_RESPONSE_CODE_HOP_LIMIT_REACHED 5.08
128 COAP_SIGNALING_CODE_CSM 7.01
129 COAP_SIGNALING_CODE_PING 7.02
130 COAP_SIGNALING_CODE_PONG 7.03
131 COAP_SIGNALING_CODE_RELEASE 7.04
132 COAP_SIGNALING_CODE_ABORT 7.05
133 NOTE: For reliable messages
135 "ttps://rfc-editor.org/rfc/rfc8323[RFC8323], this will always return
136 COAP_EMPTY_CODE.
137 Function: coap_pdu_get_mid()
139 The coap_pdu_get_mid() returns the message id from the PDU pdu header.
141 NOTE: For reliable messages RFC8323, this will always return 0.
143
145 Function: coap_pdu_get_token()
146 The coap_pdu_get_token() returns the token information held in the PDU
148 pdu token which may be zero length.
149
151 The following is the current list of options with their numeric value
152 /*
154 * The C, U, and N flags indicate the properties
155 * Critical, Unsafe, and NoCacheKey, respectively.
156 * If U is set, then N has no meaning as per
157 * https://rfc-editor.org/rfc/rfc7252#section-5.10
158 * and is set to a -.
159 * Separately, R is for the options that can be repeated
160 *
161 * The least significant byte of the option is set as followed
162 * as per https://rfc-editor.org/rfc/rfc7252#section-5.4.6
163 *
164 * 0 1 2 3 4 5 6 7
165 * --+---+---+---+---+---+---+---+
166 * | NoCacheKey| U | C |
167 * --+---+---+---+---+---+---+---+
168 *
169 * https://rfc-editor.org/rfc/rfc8613#section-4 goes on to define E, I and U
170 * properties Encrypted and Integrity Protected, Integrity Protected Only and
171 * Unprotected respectively. Integrity Protected Only is not currently used.
172 *
173 * An Option is tagged with CUNREIU with any of the letters replaced with _ if
174 * not set, or - for N if U is set (see above) for aiding understanding of the
175 * Option.
176 */
177 COAP_OPTION_IF_MATCH 1 /* C__RE__, opaque, 0-8 B, RFC7252 */
179 COAP_OPTION_URI_HOST 3 /* CU-___U, String, 1-255 B, RFC7252 */
180 COAP_OPTION_ETAG 4 /* ___RE__, opaque, 1-8 B, RFC7252 */
181 COAP_OPTION_IF_NONE_MATCH 5 /* C___E__, empty, 0 B, RFC7252 */
182 COAP_OPTION_OBSERVE 6 /* _U-_E_U, empty/uint, 0 B/0-3 B, RFC7641 */
183 COAP_OPTION_URI_PORT 7 /* CU-___U, uint, 0-2 B, RFC7252 */
184 COAP_OPTION_LOCATION_PATH 8 /* ___RE__, String, 0-255 B, RFC7252 */
185 COAP_OPTION_OSCORE 9 /* C_____U, *, 0-255 B, RFC8613 */
186 COAP_OPTION_URI_PATH 11 /* CU-RE__, String, 0-255 B, RFC7252 */
187 COAP_OPTION_CONTENT_FORMAT 12 /* ____E__, uint, 0-2 B, RFC7252 */
188 /* COAP_OPTION_MAXAGE default 60 seconds if not set */
189 COAP_OPTION_MAXAGE 14 /* _U-_E_U, uint, 0-4 B, RFC7252 */
190 COAP_OPTION_URI_QUERY 15 /* CU-RE__, String, 1-255 B, RFC7252 */
191 COAP_OPTION_HOP_LIMIT 16 /* ______U, uint, 1 B, RFC8768 */
192 COAP_OPTION_ACCEPT 17 /* C___E__, uint, 0-2 B, RFC7252 */
193 COAP_OPTION_LOCATION_QUERY 20 /* ___RE__, String, 0-255 B, RFC7252 */
194 COAP_OPTION_BLOCK2 23 /* CU-_E_U, uint, 0-3 B, RFC7959 */
195 COAP_OPTION_BLOCK1 27 /* CU-_E_U, uint, 0-3 B, RFC7959 */
196 COAP_OPTION_SIZE2 28 /* __N_E_U, uint, 0-4 B, RFC7959 */
197 COAP_OPTION_PROXY_URI 35 /* CU-___U, String, 1-1034 B, RFC7252 */
198 COAP_OPTION_PROXY_SCHEME 39 /* CU-___U, String, 1-255 B, RFC7252 */
199 COAP_OPTION_SIZE1 60 /* __N_E_U, uint, 0-4 B, RFC7252 */
200 COAP_OPTION_NORESPONSE 258 /* _U-_E_U, uint, 0-1 B, RFC7967 */
201 See FURTHER INFORMATION as to how to get the latest list.
203 Function: coap_check_option()
205 The coap_check_option() function is used to check whether the specified
207 option number is in the PDU pdu options. The option iterator oi is used
208 as a scratch (does not need to be initialized) internal storage
209 location while iterating through the options looking for the specific
210 number. If the number is repeated in the pdu, only the first occurrence
211 will be returned. If the option is not found, NULL is returned.
212 Function: coap_option_iterator_init()
214 The coap_option_iterator_init() function can be used to initialize
216 option iterator oi, applying a filter filter to indicate which options
217 are to be ignored when iterating through the options. The filter can be
218 NULL (or COAP_OPT_ALL) if all of the options are required. To set up
219 the filter otherwise, the following 4 functions are available.
220 Function: coap_option_filter_clear()
222 The coap_option_filter_clear() function initializes filter to have no
224 options set.
225 Function: coap_option_filter_get()
227 The coap_option_filter_get() function is used to check whether option
229 number is set in filter.
230 Function: coap_option_filter_set()
232 The coap_option_filter_set() function is used to set option number in
234 filter.
235 Function: coap_option_filter_unset()
237 The coap_option_filter_unset() function is used to remove option number
239 in filter.
240 Function: coap_option_next()
242 The coap_option_next() function is then used following
244 coap_option_iterator_init() in a loop to return all the appropriate
245 options until NULL is returned - indicating the end of the available
246 options. See EXAMPLES below for further information.
247 Function: coap_opt_length()
249 The coap_opt_length() function returns the length of the option opt (as
251 returned by coap_check_option() or coap_option_next()).
252 Function: coap_opt_value()
254 The coap_opt_value() function returns a pointer to the start of the
256 data for the option opt (as returned by coap_check_option() or
257 coap_option_next()).
258 Function: coap_decode_var_bytes()
260 The coap_decode_var_bytes() function will decode an option value up to
262 4 bytes long from buf and length into an unsigned 32bit number.
263 Function: coap_decode_var_bytes8()
265 The coap_decode_var_bytes8() function will decode an option value up to
267 8 bytes long from buf and length into an unsigned 64bit number.
268 Function: coap_get_uri_path()
270 The coap_get_uri_path() function will abstract the uri path from the
272 specified pdu options. The returned uri path will need to be freed off
273 when no longer required.
274
276 Function: coap_get_data()
277 The coap_get_data() function is used abstract from the pdu payload
279 information about the received data by updating length with the length
280 of data available, and data with a pointer to where the data is
281 located.
282 NOTE: This function has been updated by coap_get_data_large() when
284 large transfers may take place. See coap_block(3).
285
287 coap_check_option() and coap_option_next() returns a coap_opt_t* or
288 NULL if not found.
289 coap_decode_var_bytes() and coap_decode_var_bytes8() return the decoded
291 value.
292 coap_pdu_get_code(), coap_pdu_get_mid(), coap_pdu_get_type() return the
294 appropriate value.
295 coap_option_filter_get(), coap_option_filter_set() and
297 coap_option_filter_unset() return 1 on success or 0 on failure.
298 coap_get_data() returns 1 if data, else 0.
300 coap_opt_length() returns the option length.
302 coap_opt_value() returns a pointer to the start of the option value or
304 NULL if error.
305 coap_option_iterator_init() returns ap pointer to the provided iterator
307 or NULL on error.
308 coap_pdu_get_token() returns a pointer to the token in the pdu.
310 coap_get_uri_path() returns an allocated pointer to the uri path in the
312 pdu or NULL on error. This pointer will need to be freed off.
313
315 Abstract information from PDU
316 #include <coap3/coap.h>
318 static void
320 get_pdu_information(coap_pdu_t *pdu) {
321 int ret;
323 /* Header variables */
324 coap_pdu_type_t pdu_type;
325 coap_pdu_code_t pdu_code;
326 coap_mid_t pdu_mid;
327 /* Token variables */
328 coap_bin_const_t pdu_token;
329 /* Option variables */
330 coap_opt_iterator_t opt_iter;
331 coap_opt_t *option;
332 coap_opt_filter_t ignore_options;
333 /* Data payload variables */
335 size_t pdu_data_length;
336 const uint8_t *pdu_data;
337 size_t pdu_data_offset;
338 size_t pdu_data_total_length;
339 /* Pull in the header information */
341 pdu_type = coap_pdu_get_type(pdu);
342 pdu_code = coap_pdu_get_code(pdu);
343 pdu_mid = coap_pdu_get_mid(pdu);
344 /* Pull in the token information */
346 pdu_token = coap_pdu_get_token(pdu);
347 /* Pull in the option information */
349 /* Specific option check */
350 option = coap_check_option(pdu, COAP_OPTION_OBSERVE, &opt_iter);
351 if (option) {
352 uint32_t value = coap_decode_var_bytes(coap_opt_value(option),
353 coap_opt_length(option));
354 coap_log_info("Option OBSERVE, value %u\n", value);
355 }
356 /* Iterate through all options */
357 coap_option_iterator_init(pdu, &opt_iter, COAP_OPT_ALL);
358 while ((option = coap_option_next(&opt_iter))) {
359 coap_log_info("A: Option %d, Length %u\n",
360 opt_iter.number, coap_opt_length(option));
361 }
362 /* Iterate through options, some ignored */
363 coap_option_filter_clear(&ignore_options);
364 coap_option_filter_set(&ignore_options, COAP_OPTION_OBSERVE);
365 coap_option_iterator_init(pdu, &opt_iter, &ignore_options);
366 while ((option = coap_option_next(&opt_iter))) {
367 coap_log_info("I: Option %d, Length %u\n",
368 opt_iter.number, coap_opt_length(option));
369 }
370 /* Pull in the payload information */
372 ret = coap_get_data(pdu, &pdu_data_length, &pdu_data);
373 /* or */
374 ret = coap_get_data_large(pdu, &pdu_data_length, &pdu_data,
375 &pdu_data_offset, &pdu_data_total_length);
376 }
378
380 coap_block(3) and coap_pdu_setup(3)
381
383 See
384 "RFC7252: The Constrained Application Protocol (CoAP)"
386 "RFC8613: Object Security for Constrained RESTful Environments
388 (OSCORE)"
389 for further information.
391 See
393 https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#option-numbers
394 for the current set of defined CoAP Options.
395
397 Please report bugs on the mailing list for libcoap:
398 libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
399 https://github.com/obgm/libcoap/issues
400
402 The libcoap project <libcoap-developers@lists.sourceforge.net>
403coap_pdu_access 4.3.4 10/09/2023 COAP_PDU_ACCESS(3)