1 /* 2 * pdu.h -- CoAP message structure 3 * 4 * Copyright (C) 2010-2014 Olaf Bergmann <bergmann@tzi.org> 5 * 6 * This file is part of the CoAP library libcoap. Please see README for terms 7 * of use. 8 */ 9 10 /** 11 * @file pdu.h 12 * @brief Pre-defined constants that reflect defaults for CoAP 13 */ 14 15 #ifndef COAP_PDU_H_ 16 #define COAP_PDU_H_ 17 18 #include "uri.h" 19 20 struct coap_session_t; 21 22 #ifdef WITH_LWIP 23 #include <lwip/pbuf.h> 24 #endif 25 26 #include <stdint.h> 27 28 #define COAP_DEFAULT_PORT 5683 /* CoAP default UDP/TCP port */ 29 #define COAPS_DEFAULT_PORT 5684 /* CoAP default UDP/TCP port for secure transmission */ 30 #define COAP_DEFAULT_MAX_AGE 60 /* default maximum object lifetime in seconds */ 31 #ifndef COAP_DEFAULT_MTU 32 #define COAP_DEFAULT_MTU 1152 33 #endif /* COAP_DEFAULT_MTU */ 34 35 /* TCP Message format constants, do not modify */ 36 #define COAP_MESSAGE_SIZE_OFFSET_TCP8 13 37 #define COAP_MESSAGE_SIZE_OFFSET_TCP16 269 /* 13 + 256 */ 38 #define COAP_MESSAGE_SIZE_OFFSET_TCP32 65805 /* 269 + 65536 */ 39 40 /* Derived message size limits */ 41 #define COAP_MAX_MESSAGE_SIZE_TCP0 (COAP_MESSAGE_SIZE_OFFSET_TCP8-1) /* 12 */ 42 #define COAP_MAX_MESSAGE_SIZE_TCP8 (COAP_MESSAGE_SIZE_OFFSET_TCP16-1) /* 268 */ 43 #define COAP_MAX_MESSAGE_SIZE_TCP16 (COAP_MESSAGE_SIZE_OFFSET_TCP32-1) /* 65804 */ 44 #define COAP_MAX_MESSAGE_SIZE_TCP32 (COAP_MESSAGE_SIZE_OFFSET_TCP32+0xFFFFFFFF) 45 46 #ifndef COAP_DEFAULT_MAX_PDU_RX_SIZE 47 #if defined(WITH_CONTIKI) || defined(WITH_LWIP) 48 #define COAP_DEFAULT_MAX_PDU_RX_SIZE (COAP_MAX_MESSAGE_SIZE_TCP16+4) 49 #else 50 /* 8 MiB max-message-size plus some space for options */ 51 #define COAP_DEFAULT_MAX_PDU_RX_SIZE (8*1024*1024+256) 52 #endif 53 #endif /* COAP_DEFAULT_MAX_PDU_RX_SIZE */ 54 55 #ifndef COAP_DEBUG_BUF_SIZE 56 #if defined(WITH_CONTIKI) || defined(WITH_LWIP) 57 #define COAP_DEBUG_BUF_SIZE 128 58 #else /* defined(WITH_CONTIKI) || defined(WITH_LWIP) */ 59 /* 1024 derived from RFC7252 4.6. Message Size max payload */ 60 #define COAP_DEBUG_BUF_SIZE (8 + 1024 * 2) 61 #endif /* defined(WITH_CONTIKI) || defined(WITH_LWIP) */ 62 #endif /* COAP_DEBUG_BUF_SIZE */ 63 64 #define COAP_DEFAULT_VERSION 1 /* version of CoAP supported */ 65 #define COAP_DEFAULT_SCHEME "coap" /* the default scheme for CoAP URIs */ 66 67 /** well-known resources URI */ 68 #define COAP_DEFAULT_URI_WELLKNOWN ".well-known/core" 69 70 /* CoAP message types */ 71 72 #define COAP_MESSAGE_CON 0 /* confirmable message (requires ACK/RST) */ 73 #define COAP_MESSAGE_NON 1 /* non-confirmable message (one-shot message) */ 74 #define COAP_MESSAGE_ACK 2 /* used to acknowledge confirmable messages */ 75 #define COAP_MESSAGE_RST 3 /* indicates error in received messages */ 76 77 /* CoAP request methods */ 78 79 #define COAP_REQUEST_GET 1 80 #define COAP_REQUEST_POST 2 81 #define COAP_REQUEST_PUT 3 82 #define COAP_REQUEST_DELETE 4 83 #define COAP_REQUEST_FETCH 5 /* RFC 8132 */ 84 #define COAP_REQUEST_PATCH 6 /* RFC 8132 */ 85 #define COAP_REQUEST_IPATCH 7 /* RFC 8132 */ 86 87 /* 88 * CoAP option types (be sure to update coap_option_check_critical() when 89 * adding options 90 */ 91 92 #define COAP_OPTION_IF_MATCH 1 /* C, opaque, 0-8 B, (none) */ 93 #define COAP_OPTION_URI_HOST 3 /* C, String, 1-255 B, destination address */ 94 #define COAP_OPTION_ETAG 4 /* E, opaque, 1-8 B, (none) */ 95 #define COAP_OPTION_IF_NONE_MATCH 5 /* empty, 0 B, (none) */ 96 #define COAP_OPTION_URI_PORT 7 /* C, uint, 0-2 B, destination port */ 97 #define COAP_OPTION_LOCATION_PATH 8 /* E, String, 0-255 B, - */ 98 #define COAP_OPTION_URI_PATH 11 /* C, String, 0-255 B, (none) */ 99 #define COAP_OPTION_CONTENT_FORMAT 12 /* E, uint, 0-2 B, (none) */ 100 #define COAP_OPTION_CONTENT_TYPE COAP_OPTION_CONTENT_FORMAT 101 #define COAP_OPTION_MAXAGE 14 /* E, uint, 0--4 B, 60 Seconds */ 102 #define COAP_OPTION_URI_QUERY 15 /* C, String, 1-255 B, (none) */ 103 #define COAP_OPTION_ACCEPT 17 /* C, uint, 0-2 B, (none) */ 104 #define COAP_OPTION_LOCATION_QUERY 20 /* E, String, 0-255 B, (none) */ 105 #define COAP_OPTION_SIZE2 28 /* E, uint, 0-4 B, (none) */ 106 #define COAP_OPTION_PROXY_URI 35 /* C, String, 1-1034 B, (none) */ 107 #define COAP_OPTION_PROXY_SCHEME 39 /* C, String, 1-255 B, (none) */ 108 #define COAP_OPTION_SIZE1 60 /* E, uint, 0-4 B, (none) */ 109 110 /* option types from RFC 7641 */ 111 112 #define COAP_OPTION_OBSERVE 6 /* E, empty/uint, 0 B/0-3 B, (none) */ 113 #define COAP_OPTION_SUBSCRIPTION COAP_OPTION_OBSERVE 114 115 /* selected option types from RFC 7959 */ 116 117 #define COAP_OPTION_BLOCK2 23 /* C, uint, 0--3 B, (none) */ 118 #define COAP_OPTION_BLOCK1 27 /* C, uint, 0--3 B, (none) */ 119 120 /* selected option types from RFC 7967 */ 121 122 #define COAP_OPTION_NORESPONSE 258 /* N, uint, 0--1 B, 0 */ 123 124 #define COAP_MAX_OPT 65535 /**< the highest option number we know */ 125 126 /* CoAP result codes (HTTP-Code / 100 * 40 + HTTP-Code % 100) */ 127 128 /* As of draft-ietf-core-coap-04, response codes are encoded to base 129 * 32, i.e. the three upper bits determine the response class while 130 * the remaining five fine-grained information specific to that class. 131 */ 132 #define COAP_RESPONSE_CODE(N) (((N)/100 << 5) | (N)%100) 133 134 /* Determines the class of response code C */ 135 #define COAP_RESPONSE_CLASS(C) (((C) >> 5) & 0xFF) 136 137 #ifndef SHORT_ERROR_RESPONSE 138 /** 139 * Returns a human-readable response phrase for the specified CoAP response @p 140 * code. This function returns @c NULL if not found. 141 * 142 * @param code The response code for which the literal phrase should be 143 * retrieved. 144 * 145 * @return A zero-terminated string describing the error, or @c NULL if not 146 * found. 147 */ 148 const char *coap_response_phrase(unsigned char code); 149 150 #define COAP_ERROR_PHRASE_LENGTH 32 /**< maximum length of error phrase */ 151 152 #else 153 #define coap_response_phrase(x) ((char *)NULL) 154 155 #define COAP_ERROR_PHRASE_LENGTH 0 /**< maximum length of error phrase */ 156 #endif /* SHORT_ERROR_RESPONSE */ 157 158 /* The following definitions exist for backwards compatibility */ 159 #if 0 /* this does not exist any more */ 160 #define COAP_RESPONSE_100 40 /* 100 Continue */ 161 #endif 162 #define COAP_RESPONSE_200 COAP_RESPONSE_CODE(200) /* 2.00 OK */ 163 #define COAP_RESPONSE_201 COAP_RESPONSE_CODE(201) /* 2.01 Created */ 164 #define COAP_RESPONSE_304 COAP_RESPONSE_CODE(203) /* 2.03 Valid */ 165 #define COAP_RESPONSE_400 COAP_RESPONSE_CODE(400) /* 4.00 Bad Request */ 166 #define COAP_RESPONSE_404 COAP_RESPONSE_CODE(404) /* 4.04 Not Found */ 167 #define COAP_RESPONSE_405 COAP_RESPONSE_CODE(405) /* 4.05 Method Not Allowed */ 168 #define COAP_RESPONSE_415 COAP_RESPONSE_CODE(415) /* 4.15 Unsupported Media Type */ 169 #define COAP_RESPONSE_500 COAP_RESPONSE_CODE(500) /* 5.00 Internal Server Error */ 170 #define COAP_RESPONSE_501 COAP_RESPONSE_CODE(501) /* 5.01 Not Implemented */ 171 #define COAP_RESPONSE_503 COAP_RESPONSE_CODE(503) /* 5.03 Service Unavailable */ 172 #define COAP_RESPONSE_504 COAP_RESPONSE_CODE(504) /* 5.04 Gateway Timeout */ 173 #if 0 /* these response codes do not have a valid code any more */ 174 # define COAP_RESPONSE_X_240 240 /* Token Option required by server */ 175 # define COAP_RESPONSE_X_241 241 /* Uri-Authority Option required by server */ 176 #endif 177 #define COAP_RESPONSE_X_242 COAP_RESPONSE_CODE(402) /* Critical Option not supported */ 178 179 #define COAP_SIGNALING_CODE(N) (((N)/100 << 5) | (N)%100) 180 #define COAP_SIGNALING_CSM COAP_SIGNALING_CODE(701) 181 #define COAP_SIGNALING_PING COAP_SIGNALING_CODE(702) 182 #define COAP_SIGNALING_PONG COAP_SIGNALING_CODE(703) 183 #define COAP_SIGNALING_RELEASE COAP_SIGNALING_CODE(704) 184 #define COAP_SIGNALING_ABORT COAP_SIGNALING_CODE(705) 185 186 /* Applies to COAP_SIGNALING_CSM */ 187 #define COAP_SIGNALING_OPTION_MAX_MESSAGE_SIZE 2 188 #define COAP_SIGNALING_OPTION_BLOCK_WISE_TRANSFER 4 189 /* Applies to COAP_SIGNALING_PING / COAP_SIGNALING_PONG */ 190 #define COAP_SIGNALING_OPTION_CUSTODY 2 191 /* Applies to COAP_SIGNALING_RELEASE */ 192 #define COAP_SIGNALING_OPTION_ALTERNATIVE_ADDRESS 2 193 #define COAP_SIGNALING_OPTION_HOLD_OFF 4 194 /* Applies to COAP_SIGNALING_ABORT */ 195 #define COAP_SIGNALING_OPTION_BAD_CSM_OPTION 2 196 197 /* CoAP media type encoding */ 198 199 #define COAP_MEDIATYPE_TEXT_PLAIN 0 /* text/plain (UTF-8) */ 200 #define COAP_MEDIATYPE_APPLICATION_LINK_FORMAT 40 /* application/link-format */ 201 #define COAP_MEDIATYPE_APPLICATION_XML 41 /* application/xml */ 202 #define COAP_MEDIATYPE_APPLICATION_OCTET_STREAM 42 /* application/octet-stream */ 203 #define COAP_MEDIATYPE_APPLICATION_RDF_XML 43 /* application/rdf+xml */ 204 #define COAP_MEDIATYPE_APPLICATION_EXI 47 /* application/exi */ 205 #define COAP_MEDIATYPE_APPLICATION_JSON 50 /* application/json */ 206 #define COAP_MEDIATYPE_APPLICATION_CBOR 60 /* application/cbor */ 207 208 /* Content formats from RFC 8152 */ 209 #define COAP_MEDIATYPE_APPLICATION_COSE_SIGN 98 /* application/cose; cose-type="cose-sign" */ 210 #define COAP_MEDIATYPE_APPLICATION_COSE_SIGN1 18 /* application/cose; cose-type="cose-sign1" */ 211 #define COAP_MEDIATYPE_APPLICATION_COSE_ENCRYPT 96 /* application/cose; cose-type="cose-encrypt" */ 212 #define COAP_MEDIATYPE_APPLICATION_COSE_ENCRYPT0 16 /* application/cose; cose-type="cose-encrypt0" */ 213 #define COAP_MEDIATYPE_APPLICATION_COSE_MAC 97 /* application/cose; cose-type="cose-mac" */ 214 #define COAP_MEDIATYPE_APPLICATION_COSE_MAC0 17 /* application/cose; cose-type="cose-mac0" */ 215 216 #define COAP_MEDIATYPE_APPLICATION_COSE_KEY 101 /* application/cose-key */ 217 #define COAP_MEDIATYPE_APPLICATION_COSE_KEY_SET 102 /* application/cose-key-set */ 218 219 /* Content formats from RFC 8428 */ 220 #define COAP_MEDIATYPE_APPLICATION_SENML_JSON 110 /* application/senml+json */ 221 #define COAP_MEDIATYPE_APPLICATION_SENSML_JSON 111 /* application/sensml+json */ 222 #define COAP_MEDIATYPE_APPLICATION_SENML_CBOR 112 /* application/senml+cbor */ 223 #define COAP_MEDIATYPE_APPLICATION_SENSML_CBOR 113 /* application/sensml+cbor */ 224 #define COAP_MEDIATYPE_APPLICATION_SENML_EXI 114 /* application/senml-exi */ 225 #define COAP_MEDIATYPE_APPLICATION_SENSML_EXI 115 /* application/sensml-exi */ 226 #define COAP_MEDIATYPE_APPLICATION_SENML_XML 310 /* application/senml+xml */ 227 #define COAP_MEDIATYPE_APPLICATION_SENSML_XML 311 /* application/sensml+xml */ 228 229 /* Note that identifiers for registered media types are in the range 0-65535. We 230 * use an unallocated type here and hope for the best. */ 231 #define COAP_MEDIATYPE_ANY 0xff /* any media type */ 232 233 /** 234 * coap_tid_t is used to store CoAP transaction id, i.e. a hash value 235 * built from the remote transport address and the message id of a 236 * CoAP PDU. Valid transaction ids are greater or equal zero. 237 */ 238 typedef int coap_tid_t; 239 240 /** Indicates an invalid transaction id. */ 241 #define COAP_INVALID_TID -1 242 243 /** 244 * Indicates that a response is suppressed. This will occur for error 245 * responses if the request was received via IP multicast. 246 */ 247 #define COAP_DROPPED_RESPONSE -2 248 249 #define COAP_PDU_DELAYED -3 250 251 #define COAP_OPT_LONG 0x0F /* OC == 0b1111 indicates that the option list 252 * in a CoAP message is limited by 0b11110000 253 * marker */ 254 255 #define COAP_OPT_END 0xF0 /* end marker */ 256 257 #define COAP_PAYLOAD_START 0xFF /* payload marker */ 258 259 /** 260 * @deprecated Use coap_optlist_t instead. 261 * 262 * Structures for more convenient handling of options. (To be used with ordered 263 * coap_list_t.) The option's data will be added to the end of the coap_option 264 * structure (see macro COAP_OPTION_DATA). 265 */ 266 COAP_DEPRECATED typedef struct { 267 uint16_t key; /* the option key (no delta coding) */ 268 unsigned int length; 269 } coap_option; 270 271 #define COAP_OPTION_KEY(option) (option).key 272 #define COAP_OPTION_LENGTH(option) (option).length 273 #define COAP_OPTION_DATA(option) ((unsigned char *)&(option) + sizeof(coap_option)) 274 275 /** 276 * structure for CoAP PDUs 277 * token, if any, follows the fixed size header, then options until 278 * payload marker (0xff), then the payload if stored inline. 279 * Memory layout is: 280 * <---header--->|<---token---><---options--->0xff<---payload---> 281 * header is addressed with a negative offset to token, its maximum size is 282 * max_hdr_size. 283 * options starts at token + token_length 284 * payload starts at data, its length is used_size - (data - token) 285 */ 286 287 typedef struct coap_pdu_t { 288 uint8_t type; /**< message type */ 289 uint8_t code; /**< request method (value 1--10) or response code (value 40-255) */ 290 uint8_t max_hdr_size; /**< space reserved for protocol-specific header */ 291 uint8_t hdr_size; /**< actaul size used for protocol-specific header */ 292 uint8_t token_length; /**< length of Token */ 293 uint16_t tid; /**< transaction id, if any, in regular host byte order */ 294 uint16_t max_delta; /**< highest option number */ 295 size_t alloc_size; /**< allocated storage for token, options and payload */ 296 size_t used_size; /**< used bytes of storage for token, options and payload */ 297 size_t max_size; /**< maximum size for token, options and payload, or zero for variable size pdu */ 298 uint8_t *token; /**< first byte of token, if any, or options */ 299 uint8_t *data; /**< first byte of payload, if any */ 300 #ifdef WITH_LWIP 301 struct pbuf *pbuf; /**< lwIP PBUF. The package data will always reside 302 * inside the pbuf's payload, but this pointer 303 * has to be kept because no exact offset can be 304 * given. This field must not be accessed from 305 * outside, because the pbuf's reference count 306 * is checked to be 1 when the pbuf is assigned 307 * to the pdu, and the pbuf stays exclusive to 308 * this pdu. */ 309 #endif 310 } coap_pdu_t; 311 312 #define COAP_PDU_IS_EMPTY(pdu) ((pdu)->code == 0) 313 #define COAP_PDU_IS_REQUEST(pdu) (!COAP_PDU_IS_EMPTY(pdu) && (pdu)->code < 32) 314 #define COAP_PDU_IS_RESPONSE(pdu) ((pdu)->code >= 64 && (pdu)->code < 224) 315 #define COAP_PDU_IS_SIGNALING(pdu) ((pdu)->code >= 224) 316 317 #define COAP_PDU_MAX_UDP_HEADER_SIZE 4 318 #define COAP_PDU_MAX_TCP_HEADER_SIZE 6 319 320 #ifdef WITH_LWIP 321 /** 322 * Creates a CoAP PDU from an lwIP @p pbuf, whose reference is passed on to this 323 * function. 324 * 325 * The pbuf is checked for being contiguous, and for having only one reference. 326 * The reference is stored in the PDU and will be freed when the PDU is freed. 327 * 328 * (For now, these are fatal errors; in future, a new pbuf might be allocated, 329 * the data copied and the passed pbuf freed). 330 * 331 * This behaves like coap_pdu_init(0, 0, 0, pbuf->tot_len), and afterwards 332 * copying the contents of the pbuf to the pdu. 333 * 334 * @return A pointer to the new PDU object or @c NULL on error. 335 */ 336 coap_pdu_t *coap_pdu_from_pbuf(struct pbuf *pbuf, coap_pdu_t *recv_pdu); 337 #endif 338 339 typedef uint8_t coap_proto_t; 340 /** 341 * coap_proto_t values 342 */ 343 #define COAP_PROTO_NONE 0 344 #define COAP_PROTO_UDP 1 345 #if defined(HAVE_LIBTINYDTLS) || defined(HAVE_OPENSSL) || defined(HAVE_LIBGNUTLS) 346 #define COAP_PROTO_DTLS 2 347 #endif /* HAVE_LIBTINYDTLS || HAVE_OPENSSL || HAVE_LIBGNUTLS */ 348 #ifndef COAP_NO_TCP 349 #define COAP_PROTO_TCP 3 350 #if defined(HAVE_LIBTINYDTLS) || defined(HAVE_OPENSSL) || defined(HAVE_LIBGNUTLS) 351 #define COAP_PROTO_TLS 4 352 #endif /* HAVE_LIBTINYDTLS || HAVE_OPENSSL || HAVE_LIBGNUTLS */ 353 #endif /* COAP_NO_TCP */ 354 355 /** 356 * Creates a new CoAP PDU with at least enough storage space for the given 357 * @p size maximum message size. The function returns a pointer to the 358 * node coap_pdu_t object on success, or @c NULL on error. The storage allocated 359 * for the result must be released with coap_delete_pdu() if coap_send() is not 360 * called. 361 * 362 * @param type The type of the PDU (one of COAP_MESSAGE_CON, COAP_MESSAGE_NON, 363 * COAP_MESSAGE_ACK, COAP_MESSAGE_RST). 364 * @param code The message code. 365 * @param tid The transcation id to set or 0 if unknown / not applicable. 366 * @param size The maximum allowed number of byte for the message. 367 * @return A pointer to the new PDU object or @c NULL on error. 368 */ 369 coap_pdu_t * 370 coap_pdu_init(uint8_t type, uint8_t code, uint16_t tid, size_t size); 371 372 /** 373 * Dynamically grows the size of @p pdu to @p new_size. The new size 374 * must not exceed the PDU's configure maximum size. On success, this 375 * function returns 1, otherwise 0. 376 * 377 * @param pdu The PDU to resize. 378 * @param new_size The new size in bytes. 379 * @return 1 if the operation succeeded, 0 otherwise. 380 */ 381 int coap_pdu_resize(coap_pdu_t *pdu, size_t new_size); 382 383 /** 384 * Clears any contents from @p pdu and resets @c used_size, 385 * and @c data pointers. @c max_size is set to @p size, any 386 * other field is set to @c 0. Note that @p pdu must be a valid 387 * pointer to a coap_pdu_t object created e.g. by coap_pdu_init(). 388 */ 389 void coap_pdu_clear(coap_pdu_t *pdu, size_t size); 390 391 /** 392 * Creates a new CoAP PDU. 393 */ 394 coap_pdu_t *coap_new_pdu(const struct coap_session_t *session); 395 396 /** 397 * Dispose of an CoAP PDU and frees associated storage. 398 * Not that in general you should not call this function directly. 399 * When a PDU is sent with coap_send(), coap_delete_pdu() will be 400 * called automatically for you. 401 */ 402 403 void coap_delete_pdu(coap_pdu_t *); 404 405 /** 406 * Interprets @p data to determine the number of bytes in the header. 407 * This function returns @c 0 on error or a number greater than zero on success. 408 * 409 * @param proto Session's protocol 410 * @param data The first byte of raw data to parse as CoAP PDU. 411 * 412 * @return A value greater than zero on success or @c 0 on error. 413 */ 414 size_t coap_pdu_parse_header_size(coap_proto_t proto, 415 const uint8_t *data); 416 417 /** 418 * Parses @p data to extract the message size. 419 * @p length must be at least coap_pdu_parse_header_size(proto, data). 420 * This function returns @c 0 on error or a number greater than zero on success. 421 * 422 * @param proto Session's protocol 423 * @param data The raw data to parse as CoAP PDU. 424 * @param length The actual size of @p data. 425 * 426 * @return A value greater than zero on success or @c 0 on error. 427 */ 428 size_t coap_pdu_parse_size(coap_proto_t proto, 429 const uint8_t *data, 430 size_t length); 431 432 /** 433 * Decode the protocol specific header for the specified PDU. 434 * @param pdu A newly received PDU. 435 * @param proto The target wire protocol. 436 * @return 1 for success or 0 on error. 437 */ 438 439 int coap_pdu_parse_header(coap_pdu_t *pdu, coap_proto_t proto); 440 441 /** 442 * Verify consistency in the given CoAP PDU structure and locate the data. 443 * This function returns @c 0 on error or a number greater than zero on 444 * success. 445 * This function only parses the token and options, up to the payload start 446 * marker. 447 * 448 * @param pdu The PDU structure to. 449 * 450 * @return 1 on success or @c 0 on error. 451 */ 452 int coap_pdu_parse_opt(coap_pdu_t *pdu); 453 454 /** 455 * Parses @p data into the CoAP PDU structure given in @p result. 456 * The target pdu must be large enough to 457 * This function returns @c 0 on error or a number greater than zero on success. 458 * 459 * @param proto Session's protocol 460 * @param data The raw data to parse as CoAP PDU. 461 * @param length The actual size of @p data. 462 * @param pdu The PDU structure to fill. Note that the structure must 463 * provide space to hold at least the token and options 464 * part of the message. 465 * 466 * @return 1 on success or @c 0 on error. 467 */ 468 int coap_pdu_parse(coap_proto_t proto, 469 const uint8_t *data, 470 size_t length, 471 coap_pdu_t *pdu); 472 /** 473 * Adds token of length @p len to @p pdu. 474 * Adding the token destroys any following contents of the pdu. Hence options 475 * and data must be added after coap_add_token() has been called. In @p pdu, 476 * length is set to @p len + @c 4, and max_delta is set to @c 0. This function 477 * returns @c 0 on error or a value greater than zero on success. 478 * 479 * @param pdu The PDU where the token is to be added. 480 * @param len The length of the new token. 481 * @param data The token to add. 482 * 483 * @return A value greater than zero on success, or @c 0 on error. 484 */ 485 int coap_add_token(coap_pdu_t *pdu, 486 size_t len, 487 const uint8_t *data); 488 489 /** 490 * Adds option of given type to pdu that is passed as first 491 * parameter. 492 * coap_add_option() destroys the PDU's data, so coap_add_data() must be called 493 * after all options have been added. As coap_add_token() destroys the options 494 * following the token, the token must be added before coap_add_option() is 495 * called. This function returns the number of bytes written or @c 0 on error. 496 */ 497 size_t coap_add_option(coap_pdu_t *pdu, 498 uint16_t type, 499 size_t len, 500 const uint8_t *data); 501 502 /** 503 * Adds option of given type to pdu that is passed as first parameter, but does 504 * not write a value. It works like coap_add_option with respect to calling 505 * sequence (i.e. after token and before data). This function returns a memory 506 * address to which the option data has to be written before the PDU can be 507 * sent, or @c NULL on error. 508 */ 509 uint8_t *coap_add_option_later(coap_pdu_t *pdu, 510 uint16_t type, 511 size_t len); 512 513 /** 514 * Adds given data to the pdu that is passed as first parameter. Note that the 515 * PDU's data is destroyed by coap_add_option(). coap_add_data() must be called 516 * only once per PDU, otherwise the result is undefined. 517 */ 518 int coap_add_data(coap_pdu_t *pdu, 519 size_t len, 520 const uint8_t *data); 521 522 /** 523 * Adds given data to the pdu that is passed as first parameter but does not 524 * copyt it. Note that the PDU's data is destroyed by coap_add_option(). 525 * coap_add_data() must be have been called once for this PDU, otherwise the 526 * result is undefined. 527 * The actual data must be copied at the returned location. 528 */ 529 uint8_t *coap_add_data_after(coap_pdu_t *pdu, size_t len); 530 531 /** 532 * Retrieves the length and data pointer of specified PDU. Returns 0 on error or 533 * 1 if *len and *data have correct values. Note that these values are destroyed 534 * with the pdu. 535 */ 536 int coap_get_data(const coap_pdu_t *pdu, 537 size_t *len, 538 uint8_t **data); 539 540 /** 541 * Compose the protocol specific header for the specified PDU. 542 * @param pdu A newly composed PDU. 543 * @param proto The target wire protocol. 544 * @return Number of header bytes prepended before pdu->token or 0 on error. 545 */ 546 547 size_t coap_pdu_encode_header(coap_pdu_t *pdu, coap_proto_t proto); 548 549 #endif /* COAP_PDU_H_ */ 550