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
68 https://tools.ietf.org/html/rfc7252#section-1.2
69 The following functions provide access to the information held within a
71 PDU.
72 Header:
74 The coap_pdu_get_type() function returns one of the messages types
76 below from the PDU pdu.
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 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 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 The coap_pdu_get_mid() returns the message id from the PDU pdu.
129 Token:
131 The coap_pdu_get_token() returns the token information held in the PDU
133 pdu which may be zero length.
134 Options:
136 The following is the current list of options with their numeric value
138 /*
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 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 See FURTHER INFORMATION as to how to get the latest list.
189 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 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 To set up the filter, the following 4 functions are available.
207 The coap_option_filter_clear() function initializes filter to have no
209 options set.
210 The coap_option_filter_get() function is used to check whether option
212 number is set in filter.
213 The coap_option_filter_set() function is used to set option number in
215 filter.
216 The coap_option_filter_unset() function is used to remove option number
218 in filter.
219 The coap_opt_length() function returns the length of the option opt.
221 The coap_opt_value() function returns a pointer to the start of the
223 data for the option.
224 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 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 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 Payload:
236 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 NOTE: This function has been updated by coap_get_data_large() when
242 large transfers may take place. See coap_block(3).
243
245 coap_check_option() and coap_option_next() returns a coap_opt_t* or
246 NULL if not found.
247 coap_decode_var_bytes() and coap_decode_var_bytes8() return the decoded
249 value.
250 coap_pdu_get_code(), coap_pdu_get_mid(), coap_pdu_get_type() return the
252 appropriate value.
253 coap_option_filter_set(), coap_option_filter_set() and
255 coap_option_filter_unset() return 1 on success or 0 on failure.
256 coap_get_data() returns 1 if data, else 0.
258 coap_opt_length() returns the option length.
260 coap_opt_value() returns a pointer to the start of the option value or
262 NULL if error.
263 coap_option_iterator_init() returns ap pointer to the provided
265 interator or NULL on error.
266 coap_pdu_get_token() returns a pointer to the token in the pdu.
268 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
273 Abstract information from PDU
274 #include <coap3/coap.h>
276 static void
278 get_pdu_information(coap_pdu_t *pdu) {
279 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 /* 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 /* 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 /* Pull in the token information */
304 pdu_token = coap_pdu_get_token(pdu);
305 /* 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 /* 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 }
336
338 coap_block(3) and coap_pdu_setup(3)
339
341 See
342 "RFC7252: The Constrained Application Protocol (CoAP)"
344 "RFC8613: Object Security for Constrained RESTful Environments
346 (OSCORE)"
347 for further information.
349 See
351 https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#option-numbers
352 for the current set of defined CoAP Options.
353
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
360 The libcoap project <libcoap-developers@lists.sourceforge.net>
361coap_pdu_access 4.3.1 11/24/2022 COAP_PDU_ACCESS(3)