1 /* 2 * pdu.h -- CoAP message structure 3 * 4 * Copyright (C) 2010-2014 Olaf Bergmann <bergmann@tzi.org> 5 * 6 * SPDX-License-Identifier: BSD-2-Clause 7 * 8 * This file is part of the CoAP library libcoap. Please see README for terms 9 * of use. 10 */ 11 12 /** 13 * @file pdu.h 14 * @brief Pre-defined constants that reflect defaults for CoAP 15 */ 16 17 #ifndef COAP_PDU_H_ 18 #define COAP_PDU_H_ 19 20 #include "uri.h" 21 #include "option.h" 22 23 #ifdef WITH_LWIP 24 #include <lwip/pbuf.h> 25 #endif 26 27 #include <stdint.h> 28 29 /** 30 * @defgroup pdu PDU 31 * API functions for PDUs 32 * @{ 33 */ 34 35 #ifndef COAP_USER_DEFAULT_PORT 36 #define COAP_USER_DEFAULT_PORT 5683 /* CoAP default UDP/TCP port */ 37 #endif 38 39 #define COAP_NSTACKX_PORT COAP_USER_DEFAULT_PORT 40 41 #define COAP_DEFAULT_PORT COAP_USER_DEFAULT_PORT 42 43 #define COAPS_DEFAULT_PORT 5684 /* CoAP default UDP/TCP port for secure transmission */ 44 #define COAP_DEFAULT_MAX_AGE 60 /* default maximum object lifetime in seconds */ 45 #ifndef COAP_DEFAULT_MTU 46 #define COAP_DEFAULT_MTU 1152 47 #endif /* COAP_DEFAULT_MTU */ 48 49 #ifndef COAP_DEFAULT_HOP_LIMIT 50 #define COAP_DEFAULT_HOP_LIMIT 16 51 #endif /* COAP_DEFAULT_HOP_LIMIT */ 52 53 #define COAP_DEFAULT_SCHEME "coap" /* the default scheme for CoAP URIs */ 54 55 /** well-known resources URI */ 56 #define COAP_DEFAULT_URI_WELLKNOWN ".well-known/core" 57 58 /* CoAP message types */ 59 60 /** 61 * CoAP PDU message type definitions 62 */ 63 typedef enum coap_pdu_type_t { 64 COAP_MESSAGE_CON, /* 0 confirmable message (requires ACK/RST) */ 65 COAP_MESSAGE_NON, /* 1 non-confirmable message (one-shot message) */ 66 COAP_MESSAGE_ACK, /* 2 used to acknowledge confirmable messages */ 67 COAP_MESSAGE_RST /* 3 indicates error in received messages */ 68 } coap_pdu_type_t; 69 70 /** 71 * CoAP PDU Request methods 72 */ 73 typedef enum coap_request_t { 74 COAP_REQUEST_GET = 1, 75 COAP_REQUEST_POST, /* 2 */ 76 COAP_REQUEST_PUT, /* 3 */ 77 COAP_REQUEST_DELETE, /* 4 */ 78 COAP_REQUEST_FETCH, /* 5 RFC 8132 */ 79 COAP_REQUEST_PATCH, /* 6 RFC 8132 */ 80 COAP_REQUEST_IPATCH, /* 7 RFC 8132 */ 81 } coap_request_t; 82 83 /* 84 * CoAP option numbers (be sure to update coap_option_check_critical() and 85 * coap_add_option() when adding options 86 */ 87 88 /* 89 * The C, U, and N flags indicate the properties 90 * Critical, Unsafe, and NoCacheKey, respectively. 91 * If U is set, then N has no meaning as per 92 * https://tools.ietf.org/html/rfc7252#section-5.10 93 * and is set to a -. 94 * 95 * Separately, R is for the options that can be repeated 96 * 97 * The least significant byte of the option is set as followed 98 * as per https://tools.ietf.org/html/rfc7252#section-5.4.6 99 * 100 * 0 1 2 3 4 5 6 7 101 * --+---+---+---+---+---+---+---+ 102 * | NoCacheKey| U | C | 103 * --+---+---+---+---+---+---+---+ 104 * 105 * https://tools.ietf.org/html/rfc8613#section-4 goes on to define E, I and U 106 * properties Encrypted and Integrity Protected, Integrity Protected Only, and 107 * Unprotected respectively. Integrity Protected Only is not currently used. 108 * 109 * An Option is tagged with CUNREIU with any of the letters replaced with _ if 110 * not set, or - for N if U is set (see above) for aiding understanding of the 111 * Option. 112 */ 113 114 #define COAP_OPTION_IF_MATCH 1 /* C__RE__, opaque, 0-8 B, RFC7252 */ 115 #define COAP_OPTION_URI_HOST 3 /* CU-___U, String, 1-255 B, RFC7252 */ 116 #define COAP_OPTION_ETAG 4 /* ___RE__, opaque, 1-8 B, RFC7252 */ 117 #define COAP_OPTION_IF_NONE_MATCH 5 /* C___E__, empty, 0 B, RFC7252 */ 118 #define COAP_OPTION_OBSERVE 6 /* _U-_E_U, empty/uint,0/0-3 B, RFC7641 */ 119 #define COAP_OPTION_URI_PORT 7 /* CU-___U, uint, 0-2 B, RFC7252 */ 120 #define COAP_OPTION_LOCATION_PATH 8 /* ___RE__, String, 0-255 B, RFC7252 */ 121 #define COAP_OPTION_OSCORE 9 /* C_____U, *, 0-255 B, RFC8613 */ 122 #define COAP_OPTION_URI_PATH 11 /* CU-RE__, String, 0-255 B, RFC7252 */ 123 #define COAP_OPTION_CONTENT_FORMAT 12 /* ____E__, uint, 0-2 B, RFC7252 */ 124 #define COAP_OPTION_CONTENT_TYPE COAP_OPTION_CONTENT_FORMAT 125 /* COAP_OPTION_MAXAGE default 60 seconds if not set */ 126 #define COAP_OPTION_MAXAGE 14 /* _U-_E_U, uint, 0-4 B, RFC7252 */ 127 #define COAP_OPTION_URI_QUERY 15 /* CU-RE__, String, 1-255 B, RFC7252 */ 128 #define COAP_OPTION_HOP_LIMIT 16 /* ______U, uint, 1 B, RFC8768 */ 129 #define COAP_OPTION_ACCEPT 17 /* C___E__, uint, 0-2 B, RFC7252 */ 130 #define COAP_OPTION_LOCATION_QUERY 20 /* ___RE__, String, 0-255 B, RFC7252 */ 131 #define COAP_OPTION_BLOCK2 23 /* CU-_E_U, uint, 0-3 B, RFC7959 */ 132 #define COAP_OPTION_BLOCK1 27 /* CU-_E_U, uint, 0-3 B, RFC7959 */ 133 #define COAP_OPTION_SIZE2 28 /* __N_E_U, uint, 0-4 B, RFC7959 */ 134 #define COAP_OPTION_PROXY_URI 35 /* CU-___U, String, 1-1034 B, RFC7252 */ 135 #define COAP_OPTION_PROXY_SCHEME 39 /* CU-___U, String, 1-255 B, RFC7252 */ 136 #define COAP_OPTION_SIZE1 60 /* __N_E_U, uint, 0-4 B, RFC7252 */ 137 #define COAP_OPTION_NORESPONSE 258 /* _U-_E_U, uint, 0-1 B, RFC7967 */ 138 139 #define COAP_MAX_OPT 65535 /**< the highest option number we know */ 140 141 /* CoAP result codes (HTTP-Code / 100 * 40 + HTTP-Code % 100) */ 142 143 /* As of draft-ietf-core-coap-04, response codes are encoded to base 144 * 32, i.e. the three upper bits determine the response class while 145 * the remaining five fine-grained information specific to that class. 146 */ 147 #define COAP_RESPONSE_CODE(N) (((N)/100 << 5) | (N)%100) 148 149 /* Determines the class of response code C */ 150 #define COAP_RESPONSE_CLASS(C) (((C) >> 5) & 0xFF) 151 152 #ifndef SHORT_ERROR_RESPONSE 153 /** 154 * Returns a human-readable response phrase for the specified CoAP response @p 155 * code. This function returns @c NULL if not found. 156 * 157 * @param code The response code for which the literal phrase should be 158 * retrieved. 159 * 160 * @return A zero-terminated string describing the error, or @c NULL if not 161 * found. 162 */ 163 const char *coap_response_phrase(unsigned char code); 164 165 #define COAP_ERROR_PHRASE_LENGTH 32 /**< maximum length of error phrase */ 166 167 #else 168 #define coap_response_phrase(x) ((char *)NULL) 169 170 #define COAP_ERROR_PHRASE_LENGTH 0 /**< maximum length of error phrase */ 171 #endif /* SHORT_ERROR_RESPONSE */ 172 173 #define COAP_SIGNALING_CODE(N) (((N)/100 << 5) | (N)%100) 174 175 typedef enum coap_pdu_signaling_proto_t { 176 COAP_SIGNALING_CSM = COAP_SIGNALING_CODE(701), 177 COAP_SIGNALING_PING = COAP_SIGNALING_CODE(702), 178 COAP_SIGNALING_PONG = COAP_SIGNALING_CODE(703), 179 COAP_SIGNALING_RELEASE = COAP_SIGNALING_CODE(704), 180 COAP_SIGNALING_ABORT = COAP_SIGNALING_CODE(705), 181 } coap_pdu_signaling_proto_t; 182 183 /* Applies to COAP_SIGNALING_CSM */ 184 #define COAP_SIGNALING_OPTION_MAX_MESSAGE_SIZE 2 185 #define COAP_SIGNALING_OPTION_BLOCK_WISE_TRANSFER 4 186 /* Applies to COAP_SIGNALING_PING / COAP_SIGNALING_PONG */ 187 #define COAP_SIGNALING_OPTION_CUSTODY 2 188 /* Applies to COAP_SIGNALING_RELEASE */ 189 #define COAP_SIGNALING_OPTION_ALTERNATIVE_ADDRESS 2 190 #define COAP_SIGNALING_OPTION_HOLD_OFF 4 191 /* Applies to COAP_SIGNALING_ABORT */ 192 #define COAP_SIGNALING_OPTION_BAD_CSM_OPTION 2 193 194 /* CoAP media type encoding */ 195 196 #define COAP_MEDIATYPE_TEXT_PLAIN 0 /* text/plain (UTF-8) */ 197 #define COAP_MEDIATYPE_APPLICATION_LINK_FORMAT 40 /* application/link-format */ 198 #define COAP_MEDIATYPE_APPLICATION_XML 41 /* application/xml */ 199 #define COAP_MEDIATYPE_APPLICATION_OCTET_STREAM 42 /* application/octet-stream */ 200 #define COAP_MEDIATYPE_APPLICATION_RDF_XML 43 /* application/rdf+xml */ 201 #define COAP_MEDIATYPE_APPLICATION_EXI 47 /* application/exi */ 202 #define COAP_MEDIATYPE_APPLICATION_JSON 50 /* application/json */ 203 #define COAP_MEDIATYPE_APPLICATION_CBOR 60 /* application/cbor */ 204 #define COAP_MEDIATYPE_APPLICATION_CWT 61 /* application/cwt, RFC 8392 */ 205 206 /* Content formats from RFC 8152 */ 207 #define COAP_MEDIATYPE_APPLICATION_COSE_SIGN 98 /* application/cose; cose-type="cose-sign" */ 208 #define COAP_MEDIATYPE_APPLICATION_COSE_SIGN1 18 /* application/cose; cose-type="cose-sign1" */ 209 #define COAP_MEDIATYPE_APPLICATION_COSE_ENCRYPT 96 /* application/cose; cose-type="cose-encrypt" */ 210 #define COAP_MEDIATYPE_APPLICATION_COSE_ENCRYPT0 16 /* application/cose; cose-type="cose-encrypt0" */ 211 #define COAP_MEDIATYPE_APPLICATION_COSE_MAC 97 /* application/cose; cose-type="cose-mac" */ 212 #define COAP_MEDIATYPE_APPLICATION_COSE_MAC0 17 /* application/cose; cose-type="cose-mac0" */ 213 214 #define COAP_MEDIATYPE_APPLICATION_COSE_KEY 101 /* application/cose-key */ 215 #define COAP_MEDIATYPE_APPLICATION_COSE_KEY_SET 102 /* application/cose-key-set */ 216 217 /* Content formats from RFC 8428 */ 218 #define COAP_MEDIATYPE_APPLICATION_SENML_JSON 110 /* application/senml+json */ 219 #define COAP_MEDIATYPE_APPLICATION_SENSML_JSON 111 /* application/sensml+json */ 220 #define COAP_MEDIATYPE_APPLICATION_SENML_CBOR 112 /* application/senml+cbor */ 221 #define COAP_MEDIATYPE_APPLICATION_SENSML_CBOR 113 /* application/sensml+cbor */ 222 #define COAP_MEDIATYPE_APPLICATION_SENML_EXI 114 /* application/senml-exi */ 223 #define COAP_MEDIATYPE_APPLICATION_SENSML_EXI 115 /* application/sensml-exi */ 224 #define COAP_MEDIATYPE_APPLICATION_SENML_XML 310 /* application/senml+xml */ 225 #define COAP_MEDIATYPE_APPLICATION_SENSML_XML 311 /* application/sensml+xml */ 226 227 /* Content formats from RFC 8782 */ 228 #define COAP_MEDIATYPE_APPLICATION_DOTS_CBOR 271 /* application/dots+cbor */ 229 230 /* Note that identifiers for registered media types are in the range 0-65535. We 231 * use an unallocated type here and hope for the best. */ 232 #define COAP_MEDIATYPE_ANY 0xff /* any media type */ 233 234 /** 235 * coap_mid_t is used to store the CoAP Message ID of a CoAP PDU. 236 * Valid message ids are 0 to 2^16. Negative values are error codes. 237 */ 238 typedef int coap_mid_t; 239 240 /** Indicates an invalid message id. */ 241 #define COAP_INVALID_MID -1 242 243 /** 244 * Indicates an invalid message id. 245 * @deprecated Use COAP_INVALID_MID instead. 246 */ 247 #define COAP_INVALID_TID COAP_INVALID_MID 248 249 /** 250 * @deprecated Use coap_optlist_t instead. 251 * 252 * Structures for more convenient handling of options. (To be used with ordered 253 * coap_list_t.) The option's data will be added to the end of the coap_option 254 * structure (see macro COAP_OPTION_DATA). 255 */ 256 COAP_DEPRECATED typedef struct { 257 uint16_t key; /* the option key (no delta coding) */ 258 unsigned int length; 259 } coap_option; 260 261 #define COAP_OPTION_KEY(option) (option).key 262 #define COAP_OPTION_LENGTH(option) (option).length 263 #define COAP_OPTION_DATA(option) ((unsigned char *)&(option) + sizeof(coap_option)) 264 265 #ifdef WITH_LWIP 266 /** 267 * Creates a CoAP PDU from an lwIP @p pbuf, whose reference is passed on to this 268 * function. 269 * 270 * The pbuf is checked for being contiguous, and for having only one reference. 271 * The reference is stored in the PDU and will be freed when the PDU is freed. 272 * 273 * (For now, these are fatal errors; in future, a new pbuf might be allocated, 274 * the data copied and the passed pbuf freed). 275 * 276 * This behaves like coap_pdu_init(0, 0, 0, pbuf->tot_len), and afterwards 277 * copying the contents of the pbuf to the pdu. 278 * 279 * @return A pointer to the new PDU object or @c NULL on error. 280 */ 281 coap_pdu_t * coap_pdu_from_pbuf(struct pbuf *pbuf); 282 #endif 283 284 /** 285 * CoAP protocol types 286 */ 287 typedef enum coap_proto_t { 288 COAP_PROTO_NONE = 0, 289 COAP_PROTO_UDP, 290 COAP_PROTO_DTLS, 291 COAP_PROTO_TCP, 292 COAP_PROTO_TLS, 293 } coap_proto_t; 294 295 /** 296 * Set of codes available for a PDU. 297 */ 298 typedef enum coap_pdu_code_t { 299 COAP_EMPTY_CODE = 0, 300 301 COAP_REQUEST_CODE_GET = COAP_REQUEST_GET, 302 COAP_REQUEST_CODE_POST = COAP_REQUEST_POST, 303 COAP_REQUEST_CODE_PUT = COAP_REQUEST_PUT, 304 COAP_REQUEST_CODE_DELETE = COAP_REQUEST_DELETE, 305 COAP_REQUEST_CODE_FETCH = COAP_REQUEST_FETCH, 306 COAP_REQUEST_CODE_PATCH = COAP_REQUEST_PATCH, 307 COAP_REQUEST_CODE_IPATCH = COAP_REQUEST_IPATCH, 308 309 COAP_RESPONSE_CODE_OK = COAP_RESPONSE_CODE(200), 310 COAP_RESPONSE_CODE_CREATED = COAP_RESPONSE_CODE(201), 311 COAP_RESPONSE_CODE_DELETED = COAP_RESPONSE_CODE(202), 312 COAP_RESPONSE_CODE_VALID = COAP_RESPONSE_CODE(203), 313 COAP_RESPONSE_CODE_CHANGED = COAP_RESPONSE_CODE(204), 314 COAP_RESPONSE_CODE_CONTENT = COAP_RESPONSE_CODE(205), 315 COAP_RESPONSE_CODE_CONTINUE = COAP_RESPONSE_CODE(231), 316 COAP_RESPONSE_CODE_BAD_REQUEST = COAP_RESPONSE_CODE(400), 317 COAP_RESPONSE_CODE_UNAUTHORIZED = COAP_RESPONSE_CODE(401), 318 COAP_RESPONSE_CODE_BAD_OPTION = COAP_RESPONSE_CODE(402), 319 COAP_RESPONSE_CODE_FORBIDDEN = COAP_RESPONSE_CODE(403), 320 COAP_RESPONSE_CODE_NOT_FOUND = COAP_RESPONSE_CODE(404), 321 COAP_RESPONSE_CODE_NOT_ALLOWED = COAP_RESPONSE_CODE(405), 322 COAP_RESPONSE_CODE_NOT_ACCEPTABLE = COAP_RESPONSE_CODE(406), 323 COAP_RESPONSE_CODE_INCOMPLETE = COAP_RESPONSE_CODE(408), 324 COAP_RESPONSE_CODE_CONFLICT = COAP_RESPONSE_CODE(409), 325 COAP_RESPONSE_CODE_PRECONDITION_FAILED = COAP_RESPONSE_CODE(412), 326 COAP_RESPONSE_CODE_REQUEST_TOO_LARGE = COAP_RESPONSE_CODE(413), 327 COAP_RESPONSE_CODE_UNSUPPORTED_CONTENT_FORMAT = COAP_RESPONSE_CODE(415), 328 COAP_RESPONSE_CODE_UNPROCESSABLE = COAP_RESPONSE_CODE(422), 329 COAP_RESPONSE_CODE_TOO_MANY_REQUESTS = COAP_RESPONSE_CODE(429), 330 COAP_RESPONSE_CODE_INTERNAL_ERROR = COAP_RESPONSE_CODE(500), 331 COAP_RESPONSE_CODE_NOT_IMPLEMENTED = COAP_RESPONSE_CODE(501), 332 COAP_RESPONSE_CODE_BAD_GATEWAY = COAP_RESPONSE_CODE(502), 333 COAP_RESPONSE_CODE_SERVICE_UNAVAILABLE = COAP_RESPONSE_CODE(503), 334 COAP_RESPONSE_CODE_GATEWAY_TIMEOUT = COAP_RESPONSE_CODE(504), 335 COAP_RESPONSE_CODE_PROXYING_NOT_SUPPORTED = COAP_RESPONSE_CODE(505), 336 COAP_RESPONSE_CODE_HOP_LIMIT_REACHED = COAP_RESPONSE_CODE(508), 337 338 COAP_SIGNALING_CODE_CSM = COAP_SIGNALING_CSM, 339 COAP_SIGNALING_CODE_PING = COAP_SIGNALING_PING, 340 COAP_SIGNALING_CODE_PONG = COAP_SIGNALING_PONG, 341 COAP_SIGNALING_CODE_RELEASE = COAP_SIGNALING_RELEASE, 342 COAP_SIGNALING_CODE_ABORT = COAP_SIGNALING_ABORT 343 } coap_pdu_code_t; 344 345 /** 346 * Creates a new CoAP PDU with at least enough storage space for the given 347 * @p size maximum message size. The function returns a pointer to the 348 * node coap_pdu_t object on success, or @c NULL on error. The storage allocated 349 * for the result must be released with coap_delete_pdu() if coap_send() 350 * is not called. 351 * 352 * @param type The type of the PDU (one of COAP_MESSAGE_CON, COAP_MESSAGE_NON, 353 * COAP_MESSAGE_ACK, COAP_MESSAGE_RST). 354 * @param code The message code of the PDU. 355 * @param mid The message id to set or 0 if unknown / not applicable. 356 * @param size The maximum allowed number of byte for the message. 357 * @return A pointer to the new PDU object or @c NULL on error. 358 */ 359 coap_pdu_t *coap_pdu_init(coap_pdu_type_t type, coap_pdu_code_t code, 360 coap_mid_t mid, size_t size); 361 362 /** 363 * Creates a new CoAP PDU. 364 * 365 * @param type The type of the PDU (one of COAP_MESSAGE_CON, COAP_MESSAGE_NON, 366 * COAP_MESSAGE_ACK, COAP_MESSAGE_RST). 367 * @param code The message code of the PDU. 368 * @param session The session that will be using this PDU 369 * 370 * @return The skeletal PDU or @c NULL if failure. 371 */ 372 coap_pdu_t *coap_new_pdu(coap_pdu_type_t type, coap_pdu_code_t code, 373 coap_session_t *session); 374 375 /** 376 * Dispose of an CoAP PDU and frees associated storage. 377 * Not that in general you should not call this function directly. 378 * When a PDU is sent with coap_send(), coap_delete_pdu() will be called 379 * automatically for you. 380 * 381 * @param pdu The PDU for free off. 382 */ 383 void coap_delete_pdu(coap_pdu_t *pdu); 384 385 /** 386 * Duplicate an existing PDU. Specific options can be ignored and not copied 387 * across. The PDU data payload is not copied across. 388 * 389 * @param old_pdu The PDU to duplicate 390 * @param session The session that will be using this PDU. 391 * @param token_length The length of the token to use in this duplicated PDU. 392 * @param token The token to use in this duplicated PDU. 393 * @param drop_options A list of options not to copy into the duplicated PDU. 394 * If @c NULL, then all options are copied across. 395 * 396 * @return The duplicated PDU or @c NULL if failure. 397 */ 398 coap_pdu_t * 399 coap_pdu_duplicate(const coap_pdu_t *old_pdu, 400 coap_session_t *session, 401 size_t token_length, 402 const uint8_t *token, 403 coap_opt_filter_t *drop_options); 404 405 /** 406 * Adds token of length @p len to @p pdu. 407 * Adding the token destroys any following contents of the pdu. Hence options 408 * and data must be added after coap_add_token() has been called. In @p pdu, 409 * length is set to @p len + @c 4, and max_delta is set to @c 0. This function 410 * returns @c 0 on error or a value greater than zero on success. 411 * 412 * @param pdu The PDU where the token is to be added. 413 * @param len The length of the new token. 414 * @param data The token to add. 415 * 416 * @return A value greater than zero on success, or @c 0 on error. 417 */ 418 int coap_add_token(coap_pdu_t *pdu, 419 size_t len, 420 const uint8_t *data); 421 422 /** 423 * Adds option of given number to pdu that is passed as first 424 * parameter. 425 * coap_add_option() destroys the PDU's data, so coap_add_data() must be called 426 * after all options have been added. As coap_add_token() destroys the options 427 * following the token, the token must be added before coap_add_option() is 428 * called. This function returns the number of bytes written or @c 0 on error. 429 * 430 * Note: Where possible, the option data needs to be stripped of leading zeros 431 * (big endian) to reduce the amount of data needed in the PDU, as well as in 432 * some cases the maximum data size of an opton can be exceeded if not stripped 433 * and hence be illegal. This is done by using coap_encode_var_safe() or 434 * coap_encode_var_safe8(). 435 * 436 * @param pdu The PDU where the option is to be added. 437 * @param number The number of the new option. 438 * @param len The length of the new option. 439 * @param data The data of the new option. 440 * 441 * @return The overall length of the option or @c 0 on failure. 442 */ 443 size_t coap_add_option(coap_pdu_t *pdu, 444 coap_option_num_t number, 445 size_t len, 446 const uint8_t *data); 447 448 /** 449 * Adds given data to the pdu that is passed as first parameter. Note that the 450 * PDU's data is destroyed by coap_add_option(). coap_add_data() must be called 451 * only once per PDU, otherwise the result is undefined. 452 * 453 * @param pdu The PDU where the data is to be added. 454 * @param len The length of the data. 455 * @param data The data to add. 456 * 457 * @return @c 1 if success, else @c 0 if failure. 458 */ 459 int coap_add_data(coap_pdu_t *pdu, 460 size_t len, 461 const uint8_t *data); 462 463 /** 464 * Adds given data to the pdu that is passed as first parameter but does not 465 * copy it. Note that the PDU's data is destroyed by coap_add_option(). 466 * coap_add_data() must be have been called once for this PDU, otherwise the 467 * result is undefined. 468 * The actual data must be copied at the returned location. 469 * 470 * @param pdu The PDU where the data is to be added. 471 * @param len The length of the data. 472 * 473 * @return Where to copy the data of len to, or @c NULL is error. 474 */ 475 uint8_t *coap_add_data_after(coap_pdu_t *pdu, size_t len); 476 477 /** 478 * Retrieves the length and data pointer of specified PDU. Returns 0 on error or 479 * 1 if *len and *data have correct values. Note that these values are destroyed 480 * with the pdu. 481 * 482 * @param pdu The specified PDU. 483 * @param len Returns the length of the current data 484 * @param data Returns the ptr to the current data 485 * 486 * @return @c 1 if len and data are correctly filled in, else 487 * @c 0 if there is no data. 488 */ 489 int coap_get_data(const coap_pdu_t *pdu, 490 size_t *len, 491 const uint8_t **data); 492 493 /** 494 * Retrieves the data from a PDU, with support for large bodies of data that 495 * spans multiple PDUs. 496 * 497 * Note: The data pointed to on return is destroyed when the PDU is destroyed. 498 * 499 * @param pdu The specified PDU. 500 * @param len Returns the length of the current data 501 * @param data Returns the ptr to the current data 502 * @param offset Returns the offset of the current data from the start of the 503 * body comprising of many blocks (RFC7959) 504 * @param total Returns the total size of the body. 505 * If offset + length < total, then there is more data to follow. 506 * 507 * @return @c 1 if len, data, offset and total are correctly filled in, else 508 * @c 0 if there is no data. 509 */ 510 int coap_get_data_large(const coap_pdu_t *pdu, 511 size_t *len, 512 const uint8_t **data, 513 size_t *offset, 514 size_t *total); 515 516 /** 517 * Gets the PDU code associated with @p pdu. 518 * 519 * @param pdu The PDU object. 520 * 521 * @return The PDU code. 522 */ 523 coap_pdu_code_t coap_pdu_get_code(const coap_pdu_t *pdu); 524 525 /** 526 * Sets the PDU code in the @p pdu. 527 * 528 * @param pdu The PDU object. 529 * @param code The code to set in the PDU. 530 */ 531 void coap_pdu_set_code(coap_pdu_t *pdu, coap_pdu_code_t code); 532 533 /** 534 * Gets the PDU type associated with @p pdu. 535 * 536 * @param pdu The PDU object. 537 * 538 * @return The PDU type. 539 */ 540 coap_pdu_type_t coap_pdu_get_type(const coap_pdu_t *pdu); 541 542 /** 543 * Sets the PDU type in the @p pdu. 544 * 545 * @param pdu The PDU object. 546 * @param type The type to set for the PDU. 547 */ 548 void coap_pdu_set_type(coap_pdu_t *pdu, coap_pdu_type_t type); 549 550 /** 551 * Gets the token associated with @p pdu. 552 * 553 * @param pdu The PDU object. 554 * 555 * @return The token information. 556 */ 557 coap_bin_const_t coap_pdu_get_token(const coap_pdu_t *pdu); 558 559 /** 560 * Gets the message id associated with @p pdu. 561 * 562 * @param pdu The PDU object. 563 * 564 * @return The message id. 565 */ 566 coap_mid_t coap_pdu_get_mid(const coap_pdu_t *pdu); 567 568 /** 569 * Sets the message id in the @p pdu. 570 * 571 * @param pdu The PDU object. 572 * @param mid The message id value to set in the PDU. 573 * 574 */ 575 void coap_pdu_set_mid(coap_pdu_t *pdu, coap_mid_t mid); 576 577 /** @} */ 578 579 #endif /* COAP_PDU_H_ */ 580