1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc tw=0 3 4coap_pdu_access(3) 5================= 6:doctype: manpage 7:man source: coap_pdu_access 8:man version: @PACKAGE_VERSION@ 9:man manual: libcoap Manual 10 11NAME 12---- 13coap_pdu_access, 14coap_check_option, 15coap_decode_var_bytes, 16coap_decode_var_bytes8, 17coap_get_data, 18coap_opt_length, 19coap_opt_value, 20coap_option_filter_clear, 21coap_option_filter_get, 22coap_option_filter_set, 23coap_option_filter_unset, 24coap_option_iterator_init, 25coap_option_next, 26coap_pdu_get_code, 27coap_pdu_get_mid, 28coap_pdu_get_token, 29coap_pdu_get_type, 30coap_get_uri_path 31- Accessing CoAP PDUs 32 33SYNOPSIS 34-------- 35*#include <coap@LIBCOAP_API_VERSION@/coap.h>* 36 37*coap_opt_t *coap_check_option(const coap_pdu_t *_pdu_, 38coap_option_num_t _number_, coap_opt_iterator_t *_oi_);* 39 40*unsigned int coap_decode_var_bytes(const uint8_t *_buf_, size_t _length_);* 41 42*uint64_t coap_decode_var_bytes8(const uint8_t *_buf_, size_t _length_);* 43 44*int coap_get_data(const coap_pdu_t *_pdu_, size_t *_length, 45const uint8_t **_data_);* 46 47*uint32_t coap_opt_length(const coap_opt_t *_opt_);* 48 49*const uint8_t *coap_opt_value(const coap_opt_t *_opt_);* 50 51*void coap_option_filter_clear(coap_opt_filter_t *_filter_);* 52 53*int coap_option_filter_get(coap_opt_filter_t *_filter_, 54coap_option_num_t _number_);* 55 56*int coap_option_filter_set(coap_opt_filter_t *_filter_, 57coap_option_num_t _number_)*; 58 59*int coap_option_filter_unset(coap_opt_filter_t *_filter_, 60coap_option_num_t _number_);* 61 62*coap_opt_iterator_t *coap_option_iterator_init(const coap_pdu_t *_pdu_, 63coap_opt_iterator_t *_oi_, const coap_opt_filter_t *_filter_);* 64 65*coap_opt_t *coap_option_next(coap_opt_iterator_t *_oi_);* 66 67*coap_pdu_code_t coap_pdu_get_code(const coap_pdu_t *_pdu_);* 68 69*coap_mid_t coap_pdu_get_mid(const coap_pdu_t *_pdu_);* 70 71*coap_bin_const_t coap_pdu_get_token(const coap_pdu_t *_pdu_);* 72 73*coap_pdu_type_t coap_pdu_get_type(const coap_pdu_t *_pdu_);* 74 75*coap_string_t *coap_get_uri_path(const coap_pdu_t *_pdu_);* 76 77For specific (D)TLS library support, link with 78*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*, 79*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls* 80or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*. Otherwise, link with 81*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support. 82 83DESCRIPTION 84----------- 85The CoAP PDU is of the form 86 87--header--|--optional token--|--optional options--|--optional payload-- 88 89The terminology used is taken mainly from 90"https://rfc-editor.org/rfc/rfc7252#section-1.2[RFC7252 1.2. Terminology]". 91 92The following functions provide access to the information held within 93different parts of a PDU. 94 95PDU HEADER FUNCTIONS 96-------------------- 97 98*Function: coap_pdu_get_type()* 99 100The *coap_pdu_get_type*() function returns one of the messages types below from 101the PDU _pdu_ header. 102 103[source, c] 104---- 105COAP_MESSAGE_CON Type confirmable. 106COAP_MESSAGE_NON Type non-confirmable. 107COAP_MESSAGE_ACK Type acknowledge 108COAP_MESSAGE_RST Type reset. 109---- 110 111*NOTE:* For reliable messages https://rfc-editor.org/rfc/rfc8323[RFC8323], 112this will always return COAP_MESSAGE_CON. 113 114*Function: coap_pdu_get_code()* 115 116The *coap_pdu_get_code*() function returns one of the codes below from the 117PDU _pdu_ header. It is possible that new codes are added in over time. 118 119[source, c] 120---- 121COAP_EMPTY_CODE 0.00 122COAP_REQUEST_CODE_GET 0.01 123COAP_REQUEST_CODE_POST 0.02 124COAP_REQUEST_CODE_PUT 0.03 125COAP_REQUEST_CODE_DELETE 0.04 126COAP_REQUEST_CODE_FETCH 0.05 127COAP_REQUEST_CODE_PATCH 0.06 128COAP_REQUEST_CODE_IPATCH 0.07 129COAP_RESPONSE_CODE_OK 2.00 130COAP_RESPONSE_CODE_CREATED 2.01 131COAP_RESPONSE_CODE_DELETED 2.02 132COAP_RESPONSE_CODE_VALID 2.03 133COAP_RESPONSE_CODE_CHANGED 2.04 134COAP_RESPONSE_CODE_CONTENT 2.05 135COAP_RESPONSE_CODE_CONTINUE 2.31 136COAP_RESPONSE_CODE_BAD_REQUEST 4.00 137COAP_RESPONSE_CODE_UNAUTHORIZED 4.01 138COAP_RESPONSE_CODE_BAD_OPTION 4.02 139COAP_RESPONSE_CODE_FORBIDDEN 4.03 140COAP_RESPONSE_CODE_NOT_FOUND 4.04 141COAP_RESPONSE_CODE_NOT_ALLOWED 4.05 142COAP_RESPONSE_CODE_NOT_ACCEPTABLE 4.06 143COAP_RESPONSE_CODE_INCOMPLETE 4.08 144COAP_RESPONSE_CODE_CONFLICT 4.09 145COAP_RESPONSE_CODE_PRECONDITION_FAILED 4.12 146COAP_RESPONSE_CODE_REQUEST_TOO_LARGE 4.13 147COAP_RESPONSE_CODE_UNSUPPORTED_CONTENT_FORMAT 4.15 148COAP_RESPONSE_CODE_UNPROCESSABLE 4.22 149COAP_RESPONSE_CODE_TOO_MANY_REQUESTS 4.29 150COAP_RESPONSE_CODE_INTERNAL_ERROR 5.00 151COAP_RESPONSE_CODE_NOT_IMPLEMENTED 5.01 152COAP_RESPONSE_CODE_BAD_GATEWAY 5.02 153COAP_RESPONSE_CODE_SERVICE_UNAVAILABLE 5.03 154COAP_RESPONSE_CODE_GATEWAY_TIMEOUT 5.04 155COAP_RESPONSE_CODE_PROXYING_NOT_SUPPORTED 5.05 156COAP_RESPONSE_CODE_HOP_LIMIT_REACHED 5.08 157COAP_SIGNALING_CODE_CSM 7.01 158COAP_SIGNALING_CODE_PING 7.02 159COAP_SIGNALING_CODE_PONG 7.03 160COAP_SIGNALING_CODE_RELEASE 7.04 161COAP_SIGNALING_CODE_ABORT 7.05 162---- 163 164*NOTE:* For reliable messages "ttps://rfc-editor.org/rfc/rfc8323[RFC8323], 165this will always return COAP_EMPTY_CODE. 166 167*Function: coap_pdu_get_mid()* 168 169The *coap_pdu_get_mid*() returns the message id from the PDU _pdu_ header. 170 171*NOTE:* For reliable messages https://rfc-editor.org/rfc/rfc8323[RFC8323], 172this will always return 0. 173 174PDU TOKEN FUNCTIONS 175------------------- 176 177*Function: coap_pdu_get_token()* 178 179The *coap_pdu_get_token*() returns the token information held in the PDU _pdu_ 180token which may be zero length. 181 182PDU OPTIONS FUNCTIONS 183--------------------- 184 185The following is the current list of options with their numeric value 186---- 187/* 188 * The C, U, and N flags indicate the properties 189 * Critical, Unsafe, and NoCacheKey, respectively. 190 * If U is set, then N has no meaning as per 191 * https://rfc-editor.org/rfc/rfc7252#section-5.10 192 * and is set to a -. 193 * Separately, R is for the options that can be repeated 194 * 195 * The least significant byte of the option is set as followed 196 * as per https://rfc-editor.org/rfc/rfc7252#section-5.4.6 197 * 198 * 0 1 2 3 4 5 6 7 199 * --+---+---+---+---+---+---+---+ 200 * | NoCacheKey| U | C | 201 * --+---+---+---+---+---+---+---+ 202 * 203 * https://rfc-editor.org/rfc/rfc8613#section-4 goes on to define E, I and U 204 * properties Encrypted and Integrity Protected, Integrity Protected Only and 205 * Unprotected respectively. Integrity Protected Only is not currently used. 206 * 207 * An Option is tagged with CUNREIU with any of the letters replaced with _ if 208 * not set, or - for N if U is set (see above) for aiding understanding of the 209 * Option. 210 */ 211 212COAP_OPTION_IF_MATCH 1 /* C__RE__, opaque, 0-8 B, RFC7252 */ 213COAP_OPTION_URI_HOST 3 /* CU-___U, String, 1-255 B, RFC7252 */ 214COAP_OPTION_ETAG 4 /* ___RE__, opaque, 1-8 B, RFC7252 */ 215COAP_OPTION_IF_NONE_MATCH 5 /* C___E__, empty, 0 B, RFC7252 */ 216COAP_OPTION_OBSERVE 6 /* _U-_E_U, empty/uint, 0 B/0-3 B, RFC7641 */ 217COAP_OPTION_URI_PORT 7 /* CU-___U, uint, 0-2 B, RFC7252 */ 218COAP_OPTION_LOCATION_PATH 8 /* ___RE__, String, 0-255 B, RFC7252 */ 219COAP_OPTION_OSCORE 9 /* C_____U, *, 0-255 B, RFC8613 */ 220COAP_OPTION_URI_PATH 11 /* CU-RE__, String, 0-255 B, RFC7252 */ 221COAP_OPTION_CONTENT_FORMAT 12 /* ____E__, uint, 0-2 B, RFC7252 */ 222/* COAP_OPTION_MAXAGE default 60 seconds if not set */ 223COAP_OPTION_MAXAGE 14 /* _U-_E_U, uint, 0-4 B, RFC7252 */ 224COAP_OPTION_URI_QUERY 15 /* CU-RE__, String, 1-255 B, RFC7252 */ 225COAP_OPTION_HOP_LIMIT 16 /* ______U, uint, 1 B, RFC8768 */ 226COAP_OPTION_ACCEPT 17 /* C___E__, uint, 0-2 B, RFC7252 */ 227COAP_OPTION_LOCATION_QUERY 20 /* ___RE__, String, 0-255 B, RFC7252 */ 228COAP_OPTION_BLOCK2 23 /* CU-_E_U, uint, 0-3 B, RFC7959 */ 229COAP_OPTION_BLOCK1 27 /* CU-_E_U, uint, 0-3 B, RFC7959 */ 230COAP_OPTION_SIZE2 28 /* __N_E_U, uint, 0-4 B, RFC7959 */ 231COAP_OPTION_PROXY_URI 35 /* CU-___U, String, 1-1034 B, RFC7252 */ 232COAP_OPTION_PROXY_SCHEME 39 /* CU-___U, String, 1-255 B, RFC7252 */ 233COAP_OPTION_SIZE1 60 /* __N_E_U, uint, 0-4 B, RFC7252 */ 234COAP_OPTION_NORESPONSE 258 /* _U-_E_U, uint, 0-1 B, RFC7967 */ 235---- 236See FURTHER INFORMATION as to how to get the latest list. 237 238*Function: coap_check_option()* 239 240The *coap_check_option*() function is used to check whether the specified option 241_number_ is in the PDU _pdu_ options. The option iterator _oi_ is used as a 242scratch (does not need to be initialized) internal 243storage location while iterating through the options looking for the specific 244_number_. If the _number_ is repeated in the _pdu_, only the first occurrence 245will be returned. If the option is not found, NULL is returned. 246 247*Function: coap_option_iterator_init()* 248 249The *coap_option_iterator_init*() function can be used to 250initialize option iterator _oi_, applying a filter _filter_ to indicate which 251options are to be ignored when iterating through the options. The _filter_ can 252be NULL (or COAP_OPT_ALL) if all of the options are required. 253To set up the filter otherwise, the following 4 functions are available. 254 255*Function: coap_option_filter_clear()* 256 257The *coap_option_filter_clear*() function initializes _filter_ to have no 258options set. 259 260*Function: coap_option_filter_get()* 261 262The *coap_option_filter_get*() function is used to check whether option _number_ 263is set in _filter_. 264 265*Function: coap_option_filter_set()* 266 267The *coap_option_filter_set*() function is used to set option _number_ in 268_filter_. 269 270*Function: coap_option_filter_unset()* 271 272The *coap_option_filter_unset*() function is used to remove option _number_ in 273_filter_. 274 275*Function: coap_option_next()* 276 277The *coap_option_next*() function is then used following 278*coap_option_iterator_init*() in a loop to return all 279the appropriate options until NULL is returned - indicating the end of 280the available options. See EXAMPLES below for further information. 281 282*Function: coap_opt_length()* 283 284The *coap_opt_length*() function returns the length of the option _opt_ 285(as returned by *coap_check_option*() or *coap_option_next*()). 286 287*Function: coap_opt_value()* 288 289The *coap_opt_value*() function returns a pointer to the start of the data for 290the option _opt_ (as returned by *coap_check_option*() or *coap_option_next*()). 291 292*Function: coap_decode_var_bytes()* 293 294The *coap_decode_var_bytes*() function will decode an option value up to 4 bytes 295long from _buf_ and _length_ into an unsigned 32bit number. 296 297*Function: coap_decode_var_bytes8()* 298 299The *coap_decode_var_bytes8*() function will decode an option value up to 8 300bytes long from _buf_ and _length_ into an unsigned 64bit number. 301 302*Function: coap_get_uri_path()* 303 304The *coap_get_uri_path*() function will abstract the uri path from the 305specified _pdu_ options. The returned uri path will need to be freed off when no longer required. 306 307PDU PAYLOAD FUNCTIONS 308--------------------- 309 310*Function: coap_get_data()* 311 312The *coap_get_data*() function is used abstract from the _pdu_ payload 313information about the received data by updating _length_ with the length of 314data available, and _data_ with a pointer to where the data is located. 315 316*NOTE:* This function has been updated by *coap_get_data_large*() when large 317transfers may take place. See coap_block(3). 318 319RETURN VALUES 320------------- 321 322*coap_check_option*() and *coap_option_next*() returns a coap_opt_t* or 323NULL if not found. 324 325*coap_decode_var_bytes*() and *coap_decode_var_bytes8*() return the decoded 326value. 327 328*coap_pdu_get_code*(), *coap_pdu_get_mid*(), *coap_pdu_get_type*() return 329the appropriate value. 330 331*coap_option_filter_get*(), *coap_option_filter_set*() and 332*coap_option_filter_unset*() return 1 on success or 0 on failure. 333 334*coap_get_data*() returns 1 if data, else 0. 335 336*coap_opt_length*() returns the option length. 337 338*coap_opt_value*() returns a pointer to the start of the option value or 339NULL if error. 340 341*coap_option_iterator_init*() returns ap pointer to the provided iterator 342or NULL on error. 343 344*coap_pdu_get_token*() returns a pointer to the token in the pdu. 345 346*coap_get_uri_path*() returns an allocated pointer to the uri path in the 347pdu or NULL on error. This pointer will need to be freed off. 348 349EXAMPLES 350-------- 351*Abstract information from PDU* 352 353[source, c] 354---- 355#include <coap@LIBCOAP_API_VERSION@/coap.h> 356 357static void 358get_pdu_information(coap_pdu_t *pdu) { 359 360 int ret; 361 /* Header variables */ 362 coap_pdu_type_t pdu_type; 363 coap_pdu_code_t pdu_code; 364 coap_mid_t pdu_mid; 365 /* Token variables */ 366 coap_bin_const_t pdu_token; 367 /* Option variables */ 368 coap_opt_iterator_t opt_iter; 369 coap_opt_t *option; 370 coap_opt_filter_t ignore_options; 371 372 /* Data payload variables */ 373 size_t pdu_data_length; 374 const uint8_t *pdu_data; 375 size_t pdu_data_offset; 376 size_t pdu_data_total_length; 377 378 /* Pull in the header information */ 379 pdu_type = coap_pdu_get_type(pdu); 380 pdu_code = coap_pdu_get_code(pdu); 381 pdu_mid = coap_pdu_get_mid(pdu); 382 383 /* Pull in the token information */ 384 pdu_token = coap_pdu_get_token(pdu); 385 386 /* Pull in the option information */ 387 /* Specific option check */ 388 option = coap_check_option(pdu, COAP_OPTION_OBSERVE, &opt_iter); 389 if (option) { 390 uint32_t value = coap_decode_var_bytes(coap_opt_value(option), 391 coap_opt_length(option)); 392 coap_log_info("Option OBSERVE, value %u\n", value); 393 } 394 /* Iterate through all options */ 395 coap_option_iterator_init(pdu, &opt_iter, COAP_OPT_ALL); 396 while ((option = coap_option_next(&opt_iter))) { 397 coap_log_info("A: Option %d, Length %u\n", 398 opt_iter.number, coap_opt_length(option)); 399 } 400 /* Iterate through options, some ignored */ 401 coap_option_filter_clear(&ignore_options); 402 coap_option_filter_set(&ignore_options, COAP_OPTION_OBSERVE); 403 coap_option_iterator_init(pdu, &opt_iter, &ignore_options); 404 while ((option = coap_option_next(&opt_iter))) { 405 coap_log_info("I: Option %d, Length %u\n", 406 opt_iter.number, coap_opt_length(option)); 407 } 408 409 /* Pull in the payload information */ 410 ret = coap_get_data(pdu, &pdu_data_length, &pdu_data); 411 /* or */ 412 ret = coap_get_data_large(pdu, &pdu_data_length, &pdu_data, 413 &pdu_data_offset, &pdu_data_total_length); 414 415} 416---- 417 418SEE ALSO 419-------- 420*coap_block*(3) and *coap_pdu_setup*(3) 421 422FURTHER INFORMATION 423------------------- 424See 425 426"https://rfc-editor.org/rfc/rfc7252[RFC7252: The Constrained Application Protocol (CoAP)]" 427 428"https://rfc-editor.org/rfc/rfc8613[RFC8613: Object Security for Constrained RESTful Environments (OSCORE)]" 429 430for further information. 431 432See 433https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#option-numbers 434for the current set of defined CoAP Options. 435 436BUGS 437---- 438Please report bugs on the mailing list for libcoap: 439libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at 440https://github.com/obgm/libcoap/issues 441 442AUTHORS 443------- 444The libcoap project <libcoap-developers@lists.sourceforge.net> 445