resource/csdk/connectivity/lib/libcoap-4.1.1/pdu.h

   1 /* pdu.h -- CoAP message structure
   2  *
   3  * Copyright (C) 2010--2012 Olaf Bergmann <bergmann@tzi.org>
   4  *
   5  * This file is part of the CoAP library libcoap. Please see
   6  * README for terms of use.
   7  */
   8
   9 #ifndef _PDU_H_
  10 #define _PDU_H_
  11
  12 #include "config.h"
  13 #include "coap_list.h"
  14 #include "uri.h"
  15
  16 #ifdef WITH_LWIP
  17 #include <lwip/pbuf.h>
  18 #endif
  19
  20 /* pre-defined constants that reflect defaults for CoAP */
  21
  22 #define COAP_DEFAULT_RESPONSE_TIMEOUT  2 /* response timeout in seconds */
  23 #define COAP_DEFAULT_MAX_RETRANSMIT    4 /* max number of retransmissions */
  24 #define COAP_DEFAULT_PORT           5683 /* CoAP default UDP port */
  25 #define COAP_DEFAULT_MAX_AGE          60 /* default maximum object lifetime in seconds */
  26 #ifndef COAP_MAX_PDU_SIZE
  27 #ifdef WITH_ARDUINO
  28 #define COAP_MAX_PDU_SIZE           320 /* maximum size of a CoAP PDU for embedded platforms*/
  29 #else
  30 #define COAP_MAX_PDU_SIZE           1400 /* maximum size of a CoAP PDU for big platforms*/
  31 #endif
  32 #endif /* COAP_MAX_PDU_SIZE */
  33
  34 #define COAP_DEFAULT_VERSION           1 /* version of CoAP supported */
  35 #define COAP_DEFAULT_SCHEME        "coap" /* the default scheme for CoAP URIs */
  36
  37 /** well-known resources URI */
  38 #define COAP_DEFAULT_URI_WELLKNOWN ".well-known/core"
  39
  40 #ifdef __COAP_DEFAULT_HASH
  41 /* pre-calculated hash key for the default well-known URI */
  42 #define COAP_DEFAULT_WKC_HASHKEY   "\345\130\144\245"
  43 #endif
  44
  45 /* CoAP message types */
  46
  47 #define COAP_MESSAGE_CON               0 /* confirmable message (requires ACK/RST) */
  48 #define COAP_MESSAGE_NON               1 /* non-confirmable message (one-shot message) */
  49 #define COAP_MESSAGE_ACK               2 /* used to acknowledge confirmable messages */
  50 #define COAP_MESSAGE_RST               3 /* indicates error in received messages */
  51
  52 /* CoAP request methods */
  53
  54 #define COAP_REQUEST_GET       1
  55 #define COAP_REQUEST_POST      2
  56 #define COAP_REQUEST_PUT       3
  57 #define COAP_REQUEST_DELETE    4
  58
  59 /* CoAP option types (be sure to update check_critical when adding options */
  60
  61 #define COAP_OPTION_IF_MATCH      1 /* C, opaque, 0-8 B, (none) */
  62 #define COAP_OPTION_URI_HOST      3 /* C, String, 1-255 B, destination address */
  63 #define COAP_OPTION_ETAG          4 /* E, opaque, 1-8 B, (none) */
  64 #define COAP_OPTION_IF_NONE_MATCH 5 /* empty, 0 B, (none) */
  65 #define COAP_OPTION_URI_PORT      7 /* C, uint, 0-2 B, destination port */
  66 #define COAP_OPTION_LOCATION_PATH 8 /* E, String, 0-255 B, - */
  67 #define COAP_OPTION_URI_PATH     11 /* C, String, 0-255 B, (none) */
  68 #define COAP_OPTION_CONTENT_FORMAT 12 /* E, uint, 0-2 B, (none) */
  69 #define COAP_OPTION_CONTENT_TYPE COAP_OPTION_CONTENT_FORMAT
  70 #define COAP_OPTION_MAXAGE       14 /* E, uint, 0--4 B, 60 Seconds */
  71 #define COAP_OPTION_URI_QUERY    15 /* C, String, 1-255 B, (none) */
  72 #define COAP_OPTION_ACCEPT       17 /* C, uint,   0-2 B, (none) */
  73 #define COAP_OPTION_LOCATION_QUERY 20 /* E, String,   0-255 B, (none) */
  74 #define COAP_OPTION_PROXY_URI    35 /* C, String, 1-1034 B, (none) */
  75 #define COAP_OPTION_PROXY_SCHEME 39 /* C, String, 1-255 B, (none) */
  76 #define COAP_OPTION_SIZE1        60 /* E, uint, 0-4 B, (none) */
  77 #define COAP_OPTION_SIZE2        28 /* E, uint, 0-4 B, (none) */
  78
  79 /* option types from draft-ietf-coap-observe-09 */
  80
  81 #define COAP_OPTION_OBSERVE       6 /* E, empty/uint, 0 B/0-3 B, (none) */
  82 #define COAP_OPTION_SUBSCRIPTION  COAP_OPTION_OBSERVE
  83
  84 /* selected option types from draft-core-block-04 */
  85
  86 #define COAP_OPTION_BLOCK2       23 /* C, uint, 0--3 B, (none) */
  87 #define COAP_OPTION_BLOCK1       27 /* C, uint, 0--3 B, (none) */
  88
  89 #define COAP_MAX_OPT             63 /**< the highest option number we know */
  90
  91 /* CoAP result codes (HTTP-Code / 100 * 40 + HTTP-Code % 100) */
  92
  93 /* As of draft-ietf-core-coap-04, response codes are encoded to base
  94  * 32, i.e.  the three upper bits determine the response class while
  95  * the remaining five fine-grained information specific to that class.
  96  */
  97 #define COAP_RESPONSE_CODE(N) (((N)/100 << 5) | (N)%100)
  98
  99 /* Determines the class of response code C */
 100 #define COAP_RESPONSE_CLASS(C) (((C) >> 5) & 0xFF)
 101
 102 #ifndef SHORT_ERROR_RESPONSE
 103 /**
 104  * Returns a human-readable response phrase for the specified CoAP
 105  * response @p code. This function returns @c NULL if not found.
 106  *
 107  * @param code The response code for which the literal phrase should
 108  * be retrieved.
 109  *
 110  * @return A zero-terminated string describing the error, or @c NULL
 111  * if not found.
 112  */
 113 char *coap_response_phrase(unsigned char code);
 114
 115 #define COAP_ERROR_PHRASE_LENGTH 32 /**< maximum length of error phrase */
 116
 117 #else
 118 #define coap_response_phrase(x) ((char *)NULL)
 119
 120 #define COAP_ERROR_PHRASE_LENGTH 0 /**< maximum length of error phrase */
 121 #endif /* SHORT_ERROR_RESPONSE */
 122
 123 /* The following definitions exist for backwards compatibility */
 124 #if 0 /* this does not exist any more */
 125 #define COAP_RESPONSE_100      40 /* 100 Continue */
 126 #endif
 127 #define COAP_RESPONSE_200      COAP_RESPONSE_CODE(200)  /* 2.00 OK */
 128 #define COAP_RESPONSE_201      COAP_RESPONSE_CODE(201)  /* 2.01 Created */
 129 #define COAP_RESPONSE_304      COAP_RESPONSE_CODE(203)  /* 2.03 Valid */
 130 #define COAP_RESPONSE_400      COAP_RESPONSE_CODE(400)  /* 4.00 Bad Request */
 131 #define COAP_RESPONSE_404      COAP_RESPONSE_CODE(404)  /* 4.04 Not Found */
 132 #define COAP_RESPONSE_405      COAP_RESPONSE_CODE(405)  /* 4.05 Method Not Allowed */
 133 #define COAP_RESPONSE_415      COAP_RESPONSE_CODE(415)  /* 4.15 Unsupported Media Type */
 134 #define COAP_RESPONSE_500      COAP_RESPONSE_CODE(500)  /* 5.00 Internal Server Error */
 135 #define COAP_RESPONSE_501      COAP_RESPONSE_CODE(501)  /* 5.01 Not Implemented */
 136 #define COAP_RESPONSE_503      COAP_RESPONSE_CODE(503)  /* 5.03 Service Unavailable */
 137 #define COAP_RESPONSE_504      COAP_RESPONSE_CODE(504)  /* 5.04 Gateway Timeout */
 138 #if 0  /* these response codes do not have a valid code any more */
 139 #  define COAP_RESPONSE_X_240    240   /* Token Option required by server */
 140 #  define COAP_RESPONSE_X_241    241   /* Uri-Authority Option required by server */
 141 #endif
 142 #define COAP_RESPONSE_X_242    COAP_RESPONSE_CODE(402)  /* Critical Option not supported */
 143
 144 /* CoAP media type encoding */
 145
 146 #define COAP_MEDIATYPE_TEXT_PLAIN                     0 /* text/plain (UTF-8) */
 147 #define COAP_MEDIATYPE_APPLICATION_LINK_FORMAT       40 /* application/link-format */
 148 #define COAP_MEDIATYPE_APPLICATION_XML               41 /* application/xml */
 149 #define COAP_MEDIATYPE_APPLICATION_OCTET_STREAM      42 /* application/octet-stream */
 150 #define COAP_MEDIATYPE_APPLICATION_RDF_XML           43 /* application/rdf+xml */
 151 #define COAP_MEDIATYPE_APPLICATION_EXI               47 /* application/exi  */
 152 #define COAP_MEDIATYPE_APPLICATION_JSON              50 /* application/json  */
 153 #define COAP_MEDIATYPE_APPLICATION_CBOR              60 /* application/cbor  */
 154
 155 /* Note that identifiers for registered media types are in the range 0-65535. We
 156  * use an unallocated type here and hope for the best. */
 157 #define COAP_MEDIATYPE_ANY                         0xff /* any media type */
 158
 159 /* CoAP transaction id */
 160 /*typedef unsigned short coap_tid_t; */
 161 typedef int coap_tid_t;
 162 #define COAP_INVALID_TID -1
 163
 164 #define COAP_TCP_HEADER_NO_FIELD    2
 165 #define COAP_TCP_HEADER_8_BIT       3
 166 #define COAP_TCP_HEADER_16_BIT      4
 167 #define COAP_TCP_HEADER_32_BIT      6
 168
 169 #define COAP_TCP_LENGTH_FIELD_8_BIT      13
 170 #define COAP_TCP_LENGTH_FIELD_16_BIT     269
 171 #define COAP_TCP_LENGTH_FIELD_32_BIT     65805
 172
 173 #define COAP_TCP_LENGTH_LIMIT_8_BIT      13
 174 #define COAP_TCP_LENGTH_LIMIT_16_BIT     256
 175 #define COAP_TCP_LENGTH_LIMIT_32_BIT     65536
 176
 177 #define COAP_TCP_LENGTH_FIELD_NUM_8_BIT      13
 178 #define COAP_TCP_LENGTH_FIELD_NUM_16_BIT     14
 179 #define COAP_TCP_LENGTH_FIELD_NUM_32_BIT     15
 180
 181 #define COAP_OPTION_FIELD_8_BIT      12
 182 #define COAP_OPTION_FIELD_16_BIT     256
 183 #define COAP_OPTION_FIELD_32_BIT     65536
 184
 185 typedef enum
 186 {
 187     coap_udp = 0,
 188     coap_tcp,
 189     coap_tcp_8bit,
 190     coap_tcp_16bit,
 191     coap_tcp_32bit
 192 } coap_transport_type;
 193
 194 #ifdef WORDS_BIGENDIAN
 195 typedef union
 196 {
 197     typedef struct
 198     {
 199         unsigned int version:2; /* protocol version */
 200         unsigned int type:2; /* type flag */
 201         unsigned int token_length:4; /* length of Token */
 202         unsigned int code:8; /* request method (value 1--10) or response code (value 40-255) */
 203         unsigned short id; /* message id */
 204         unsigned char token[]; /* the actual token, if any */
 205     } coap_hdr_udp_t;
 206
 207
 208     struct
 209     {
 210         unsigned int message_length :4; /* length of message */
 211         unsigned int token_length :4;   /* length of Token */
 212         unsigned int code :8; /* request method (value 1--10) or response code (value 40-255) */
 213         unsigned char token[]; /* the actual token, if any */
 214     } coap_hdr_tcp_t;
 215
 216     struct
 217     {
 218         unsigned int message_length :4; /* length of message */
 219         unsigned int token_length :4;   /* length of Token */
 220         unsigned int length_byte :8;       /* extend length of message */
 221         unsigned int code :8; /* request method (value 1--10) or response code (value 40-255) */
 222         unsigned char token[]; /* the actual token, if any */
 223     } coap_hdr_tcp_8bit_t;
 224
 225     struct
 226     {
 227         unsigned int message_length :4; /* length of message */
 228         unsigned int token_length :4;   /* length of Token */
 229         unsigned short length_byte :16;       /* extend length of message */
 230         unsigned int code :8; /* request method (value 1--10) or response code (value 40-255) */
 231         unsigned char token[]; /* the actual token, if any */
 232     } coap_hdr_tcp_16bit_t;
 233
 234     struct
 235     {
 236         unsigned char header_data[6];
 237         unsigned char token[]; /* the actual token, if any */
 238     } coap_hdr_tcp_32bit_t;
 239
 240 } coap_hdr_t;
 241 #else
 242 typedef union
 243 {
 244     struct
 245     {
 246         unsigned int token_length :4; /* length of Token */
 247         unsigned int type :2; /* type flag */
 248         unsigned int version :2; /* protocol version */
 249         unsigned int code :8; /* request method (value 1--10) or response code (value 40-255) */
 250         unsigned short id; /* transaction id (network byte order!) */
 251         unsigned char token[]; /* the actual token, if any */
 252     } coap_hdr_udp_t;
 253
 254     struct
 255     {
 256         unsigned int token_length :4;   /* length of Token */
 257         unsigned int message_length :4; /* length of message */
 258         unsigned int code :8; /* request method (value 1--10) or response code (value 40-255) */
 259         unsigned char token[]; /* the actual token, if any */
 260     } coap_hdr_tcp_t;
 261
 262     struct
 263     {
 264         unsigned int token_length :4;   /* length of Token */
 265         unsigned int message_length :4; /* length of message */
 266         unsigned int length_byte :8;       /* extend length of message */
 267         unsigned int code :8; /* request method (value 1--10) or response code (value 40-255) */
 268         unsigned char token[]; /* the actual token, if any */
 269     } coap_hdr_tcp_8bit_t;
 270
 271     struct
 272     {
 273         unsigned char header_data[COAP_TCP_HEADER_16_BIT];
 274         unsigned char token[]; /* the actual token, if any */
 275     } coap_hdr_tcp_16bit_t;
 276
 277     struct
 278     {
 279         unsigned char header_data[COAP_TCP_HEADER_32_BIT];
 280         unsigned char token[]; /* the actual token, if any */
 281     } coap_hdr_tcp_32bit_t;
 282
 283 } coap_hdr_t;
 284 #endif
 285
 286 #define COAP_MESSAGE_IS_EMPTY(MSG)    ((MSG).code == 0)
 287 #define COAP_MESSAGE_IS_REQUEST(MSG)  (!COAP_MESSAGE_IS_EMPTY(MSG)  \
 288                        && ((MSG).code < 32))
 289 #define COAP_MESSAGE_IS_RESPONSE(MSG) ((MSG).code >= 64 && (MSG).code <= 191)
 290
 291 #define COAP_OPT_LONG 0x0F  /* OC == 0b1111 indicates that the option list in a
 292                  * CoAP message is limited by 0b11110000 marker */
 293
 294 #define COAP_OPT_END 0xF0   /* end marker */
 295
 296 #define COAP_PAYLOAD_START 0xFF /* payload marker */
 297
 298 /**
 299  * Structures for more convenient handling of options. (To be used with ordered
 300  * coap_list_t.) The option's data will be added to the end of the coap_option
 301  * structure (see macro COAP_OPTION_DATA).
 302  */
 303 typedef struct
 304 {
 305     unsigned short key; /* the option key (no delta coding) */
 306     unsigned int length;
 307 } coap_option;
 308
 309 #define COAP_OPTION_KEY(option) (option).key
 310 #define COAP_OPTION_LENGTH(option) (option).length
 311 #define COAP_OPTION_DATA(option) ((unsigned char *)&(option) + sizeof(coap_option))
 312
 313 /** Header structure for CoAP PDUs */
 314
 315 typedef struct
 316 {
 317     size_t max_size; /**< allocated storage for options and data */
 318
 319     coap_hdr_t *hdr;
 320     unsigned short max_delta; /**< highest option number */
 321     unsigned int length; /**< PDU length (including header, options, data)  */
 322     unsigned char *data; /**< payload */
 323
 324 #ifdef WITH_LWIP
 325     struct pbuf
 326             *pbuf; /**< lwIP PBUF. The allocated coap_pdu_t will always reside inside the pbuf's payload, but the pointer has to be kept because no exact offset can be given. This field must not be accessed from outside, because the pbuf's reference count is checked to be 1 when the pbuf is assigned to the pdu, and the pbuf stays exclusive to this pdu. */
 327 #endif
 328
 329 } coap_pdu_t;
 330
 331 /** Options in coap_pdu_t are accessed with the macro COAP_OPTION. */
 332 #define COAP_OPTION(node) ((coap_option *)(node)->options)
 333
 334 #ifdef WITH_LWIP
 335 /**
 336  * Creates a CoAP PDU from an lwIP @p pbuf, whose reference is passed on to
 337  * this function.
 338  *
 339  * The pbuf is checked for being contiguous, for having enough head space for
 340  * the PDU struct (which is located directly in front of the data, overwriting
 341  * the old other headers), and for having only one reference. The reference is
 342  * stored in the PDU and will be freed when the PDU is freed.
 343  *
 344  * (For now, these are errors; in future, a new pbuf might be allocated, the
 345  * data copied and the passed pbuf freed).
 346  *
 347  * This behaves like coap_pdu_init(0, 0, 0, pbuf->tot_len), and afterwards
 348  * copying the contents of the pbuf to the pdu.
 349  *
 350  * @return A pointer to the new PDU object or @c NULL on error.
 351  */
 352 coap_pdu_t * coap_pdu_from_pbuf(struct pbuf *pbuf);
 353 #endif
 354
 355 /**
 356  * Creates a new CoAP PDU of given @p size (must be large enough to hold the
 357  * basic CoAP message header (coap_hdr_t). The function returns a pointer to
 358  * the node coap_pdu_t object on success, or @c NULL on error. The storage
 359  * allocated for the result must be released with coap_delete_pdu().
 360  *
 361  * @param type The type of the PDU (one of COAP_MESSAGE_CON,
 362  *             COAP_MESSAGE_NON, COAP_MESSAGE_ACK, COAP_MESSAGE_RST).
 363  * @param code The message code.
 364  * @param id   The message id to set or COAP_INVALID_TID if unknown.
 365  * @param size The number of bytes to allocate for the actual message.
 366  * @param transport The transport type.
 367  *
 368  * @return A pointer to the new PDU object or @c NULL on error.
 369  */
 370 coap_pdu_t *
 371 coap_pdu_init(unsigned char type, unsigned char code, unsigned short id,
 372               size_t size, coap_transport_type transport);
 373
 374 /**
 375  * Clears any contents from @p pdu and resets @c version field, @c
 376  * length and @c data pointers. @c max_size is set to @p size, any
 377  * other field is set to @c 0. Note that @p pdu must be a valid
 378  * pointer to a coap_pdu_t object created e.g. by coap_pdu_init().
 379  */
 380 void coap_pdu_clear(coap_pdu_t *pdu, size_t size, coap_transport_type transport,
 381                     unsigned int length);
 382
 383 /**
 384  * Creates a new CoAP PDU. The object is created on the heap and must be released
 385  * using coap_delete_pdu();
 386  *
 387  * @deprecated This function allocates the maximum storage for each
 388  * PDU. Use coap_pdu_init() instead.
 389  */
 390 coap_pdu_t *coap_new_pdu(coap_transport_type transport, unsigned int size);
 391
 392 void coap_delete_pdu(coap_pdu_t *);
 393
 394 /**
 395  * Parses @p data into the CoAP PDU structure given in @p result. This
 396  * function returns @c 0 on error or a number greater than zero on
 397  * success.
 398  *
 399  * @param data   The raw data to parse as CoAP PDU
 400  * @param length The actual size of @p data
 401  * @param result The PDU structure to fill. Note that the structure must
 402  *               provide space for at least @p length bytes to hold the
 403  *               entire CoAP PDU.
 404  * @param transport The transport type.
 405  * @return A value greater than zero on success or @c 0 on error.
 406  */
 407 int coap_pdu_parse(unsigned char *data, size_t length, coap_pdu_t *pdu,
 408                    coap_transport_type transport);
 409
 410 #ifdef WITH_TCP
 411 /**
 412  * Get transport type of coap header for coap over tcp through payload size.
 413  *
 414  * @param size   payload size of pdu.
 415  * @return The transport type.
 416  */
 417 coap_transport_type coap_get_tcp_header_type_from_size(unsigned int size);
 418
 419 /**
 420  * Get transport type of coap header for coap over tcp through init-byte.
 421  *
 422  * @param legnth   length value of init byte.
 423 * @return The transport type.
 424  */
 425 coap_transport_type coap_get_tcp_header_type_from_initbyte(unsigned int length);
 426
 427 /**
 428  * Add length value in field of coap header for coap over tcp.
 429  *
 430  * @param pdu  The pdu pointer.
 431  * @param transport The transport type.
 432  * @param length  length value of init byte.
 433  */
 434 void coap_add_length(const coap_pdu_t *pdu, coap_transport_type transport,
 435                      unsigned int length);
 436
 437 /**
 438  * Get the value of length field of coap header for coap over tcp.
 439  *
 440  * @param pdu  The pdu pointer.
 441  * @param transport The transport type.
 442  * @return length value of init byte.
 443  */
 444 unsigned int coap_get_length(const coap_pdu_t *pdu, coap_transport_type transport);
 445
 446 /**
 447  * Get pdu length from header of coap over tcp.
 448  *
 449  * @param header   The header to parse.
 450  * @return transport The transport type.
 451  */
 452 unsigned int coap_get_length_from_header(const unsigned char *header, coap_transport_type transport);
 453
 454 /**
 455  * Get length of header for coap over tcp.
 456  *
 457  * @param data   The raw data to parse as CoAP PDU
 458  * @return header length + token length
 459  */
 460 unsigned int coap_get_tcp_header_length(unsigned char *data);
 461
 462 /**
 463  * Get length of header without token length for coap over tcp.
 464  *
 465  * @param transport The transport type.
 466  * @return header length.
 467  */
 468 unsigned int coap_get_tcp_header_length_for_transport(coap_transport_type transport);
 469
 470 /**
 471  * Get option length.
 472  *
 473  * @param key      delta of option
 474  * @param length   length of option
 475  * @return total option length
 476  */
 477 size_t coap_get_opt_header_length(unsigned short key, size_t length);
 478 #endif
 479
 480 /**
 481  * Add code in coap header.
 482  *
 483  * @param pdu  The pdu pointer.
 484  * @param transport The transport type.
 485  * @param code  The message code.
 486  */
 487 void coap_add_code(const coap_pdu_t *pdu, coap_transport_type transport,
 488                    unsigned int code);
 489
 490 /**
 491  * Get message code from coap header
 492  *
 493  * @param pdu  The pdu pointer.
 494  * @param transport The transport type.
 495  * @return The message code.
 496  */
 497 unsigned int coap_get_code(const coap_pdu_t *pdu, coap_transport_type transport);
 498 /**
 499  * Adds token of length @p len to @p pdu. Adding the token destroys
 500  * any following contents of the pdu. Hence options and data must be
 501  * added after coap_add_token() has been called. In @p pdu, length is
 502  * set to @p len + @c 4, and max_delta is set to @c 0.  This funtion
 503  * returns @c 0 on error or a value greater than zero on success.
 504  *
 505  * @param pdu  The pdu pointer.
 506  * @param len  The length of the new token.
 507  * @param data The token to add.
 508  * @param transport The transport type.
 509  * @return A value greater than zero on success, or @c 0 on error.
 510  */
 511 int coap_add_token(coap_pdu_t *pdu, size_t len, const unsigned char *data,
 512                    coap_transport_type transport);
 513
 514 /**
 515  * Get token from coap header base on transport type
 516  *
 517  * @param pdu_hdr  The header pointer of PDU.
 518  * @param transport The transport type.
 519  * @param token  out parameter to get token.
 520  * @param token_length  out parameter to get token length.
 521  */
 522 void coap_get_token(const coap_hdr_t *pdu_hdr, coap_transport_type transport,
 523                     unsigned char **token, unsigned int *token_length);
 524
 525 /**
 526  * Adds option of given type to pdu that is passed as first
 527  * parameter. coap_add_option() destroys the PDU's data, so
 528  * coap_add_data() must be called after all options have been added.
 529  * As coap_add_token() destroys the options following the token,
 530  * the token must be added before coap_add_option() is called.
 531  * This function returns the number of bytes written or @c 0 on error.
 532  */
 533 size_t coap_add_option(coap_pdu_t *pdu, unsigned short type, unsigned int len,
 534         const unsigned char *data, coap_transport_type transport);
 535
 536 /**
 537  * Adds option of given type to pdu that is passed as first
 538  * parameter, but does not write a val13ue. It works like coap_add_option with
 539  * respect to calling sequence (i.e. after token and before data).
 540  * This function returns a memory address to which the option data has to be
 541  * written before the PDU can be sent, or @c NULL on error.
 542  */
 543 unsigned char *coap_add_option_later(coap_pdu_t *pdu, unsigned short type, unsigned int len);
 544
 545 /**
 546  * Adds given data to the pdu that is passed as first parameter. Note
 547  * that the PDU's data is destroyed by coap_add_option(). coap_add_data()
 548  * must be called only once per PDU, otherwise the result is undefined.
 549  */
 550 int coap_add_data(coap_pdu_t *pdu, unsigned int len, const unsigned char *data);
 551
 552 /**
 553  * Retrieves the length and data pointer of specified PDU. Returns 0 on error
 554  * or 1 if *len and *data have correct values. Note that these values are
 555  * destroyed with the pdu.
 556  */
 557 int coap_get_data(const coap_pdu_t *pdu, size_t *len, unsigned char **data);
 558
 559 #endif /* _PDU_H_ */