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 - Accessing CoAP PDUs
9
11 #include <coap3/coap.h>
12 coap_opt_t *coap_check_option(const coap_pdu_t *pdu, coap_option_num_t
14 number, coap_opt_iterator_t *oi);
15 unsigned int coap_decode_var_bytes(const uint8_t *buf, size_t length);
17 uint64_t coap_decode_var_bytes8(const uint8_t *buf, size_t length);
19 int coap_get_data(const coap_pdu_t *pdu, size_t *length, const uint8_t
21 **_data);
22 uint32_t coap_opt_length(const coap_opt_t *opt);
24 const uint8_t *coap_opt_value(const coap_opt_t *opt);
26 void coap_option_filter_clear(coap_opt_filter_t *filter);
28 int coap_option_filter_get(coap_opt_filter_t *filter, coap_option_num_t
30 number);
31 int coap_option_filter_set(coap_opt_filter_t *filter, coap_option_num_t
33 number);
34 int coap_option_filter_unset(coap_opt_filter_t *filter,
36 coap_option_num_t number);
37 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 coap_opt_t *coap_option_next(coap_opt_iterator_t *oi);
42 coap_pdu_code_t coap_pdu_get_code(const coap_pdu_t *pdu);
44 coap_mid_t coap_pdu_get_mid(const coap_pdu_t *pdu);
46 coap_bin_const_t coap_pdu_get_token(const coap_pdu_t *pdu);
48 coap_pdu_type_t coap_pdu_get_type(const coap_pdu_t *pdu);
50 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
57 The CoAP PDU is of the form
58 --header--|--optional token--|--optional options--|--optional payload--
60 The terminology used is taken mainly from
62 https://tools.ietf.org/html/rfc7252#section-1.2
63 The following functions provide access to the information held within a
65 PDU.
66 Header:
68 The coap_pdu_get_type() function returns one of the messages types
70 below from the PDU pdu.
71 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 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 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 The coap_pdu_get_mid() returns the message id from the PDU pdu.
123 Token:
125 The coap_pdu_get_token() returns the token information held in the PDU
127 pdu which may be zero length.
128 Options:
130 The following is the current list of options with their numeric value
132 /*
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 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 See FURTHER INFORMATION as to how to get the latest list.
183 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 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 To set up the filter, the following 4 functions are available.
201 The coap_option_filter_clear() function initializes filter to have no
203 options set.
204 The coap_option_filter_get() function is used to check whether option
206 number is set in filter.
207 The coap_option_filter_set() function is used to set option number in
209 filter.
210 The coap_option_filter_unset() function is used to remove option number
212 in filter.
213 The coap_opt_length() function returns the length of the option opt.
215 The coap_opt_val() function returns a pointer to the start of the data
217 for the option.
218 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 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 Payload:
226 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 NOTE: This function has been updated by coap_get_data_large() when
232 large transfers may take place. See coap_block(3).
233
235 Abstract information from PDU
236 #include <coap3/coap.h>
238 static void
240 get_pdu_information(coap_pdu_t *pdu) {
241 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 /* 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 /* 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 /* Pull in the token information */
266 pdu_token = coap_pdu_get_token(pdu);
267 /* 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 /* 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 }
298
300 coap_block(3) and coap_pdu_setup(3)
301
303 See
304 "RFC7252: The Constrained Application Protocol (CoAP)"
306 "RFC8613: Object Security for Constrained RESTful Environments
308 (OSCORE)"
309 for further information.
311 See
313 https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#option-numbers
314 for the current set of defined CoAP Options.
315
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
322 The libcoap project <libcoap-developers@lists.sourceforge.net>
323coap_pdu_access 4.3.0 01/20/2022 COAP_PDU_ACCESS(3)