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