resource/csdk/connectivity/lib/libcoap-4.1.1/include/coap/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 _COAP_PDU_H_
  10 #define _COAP_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 response @p
 105  * code. This function returns @c NULL if not found.
 106  *
 107  * @param code The response code for which the literal phrase should be
 108  *             retrieved.
 109  *
 110  * @return     A zero-terminated string describing the error, or @c NULL if not
 111  *             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 /**
 160   * coap_tid_t is used to store CoAP transaction id, i.e. a hash value
 161   * built from the remote transport address and the message id of a
 162   * CoAP PDU.  Valid transaction ids are greater or equal zero.
 163   */
 164 typedef int coap_tid_t;
 165
 166 /** Indicates an invalid transaction id. */
 167 #define COAP_INVALID_TID -1
 168
 169 #define COAP_TCP_HEADER_NO_FIELD    2
 170 #define COAP_TCP_HEADER_8_BIT       3
 171 #define COAP_TCP_HEADER_16_BIT      4
 172 #define COAP_TCP_HEADER_32_BIT      6
 173
 174 #define COAP_TCP_LENGTH_FIELD_8_BIT      13
 175 #define COAP_TCP_LENGTH_FIELD_16_BIT     269
 176 #define COAP_TCP_LENGTH_FIELD_32_BIT     65805
 177
 178 #define COAP_TCP_LENGTH_LIMIT_8_BIT      13
 179 #define COAP_TCP_LENGTH_LIMIT_16_BIT     256
 180 #define COAP_TCP_LENGTH_LIMIT_32_BIT     65536
 181
 182 #define COAP_TCP_LENGTH_FIELD_NUM_8_BIT      13
 183 #define COAP_TCP_LENGTH_FIELD_NUM_16_BIT     14
 184 #define COAP_TCP_LENGTH_FIELD_NUM_32_BIT     15
 185
 186 #define COAP_OPTION_FIELD_8_BIT      12
 187 #define COAP_OPTION_FIELD_16_BIT     256
 188 #define COAP_OPTION_FIELD_32_BIT     65536
 189
 190 typedef enum {
 191     COAP_UDP = 0,
 192     COAP_TCP,
 193     COAP_TCP_8BIT,
 194     COAP_TCP_16BIT,
 195     COAP_TCP_32BIT
 196 } coap_transport_t;
 197
 198 #ifdef WORDS_BIGENDIAN
 199 typedef struct {
 200   unsigned short version:2;      /* protocol version */
 201   unsigned short type:2;         /* type flag */
 202   unsigned short token_length:4; /* length of Token */
 203   unsigned short code:8;         /* request method (value 1--10) or response
 204                                     code (value 40-255) */
 205   unsigned short id;             /* message id */
 206   unsigned char token[];         /* the actual token, if any */
 207 } coap_hdr_udp_t;
 208 #else
 209 typedef struct {
 210   unsigned short token_length:4; /* length of Token */
 211   unsigned short type:2;         /* type flag */
 212   unsigned short version:2;      /* protocol version */
 213   unsigned short code:8;         /* request method (value 1--10) or response
 214                                     code (value 40-255) */
 215   unsigned short id;             /* transaction id (network byte order!) */
 216   unsigned char token[];         /* the actual token, if any */
 217 } coap_hdr_udp_t;
 218 #endif
 219
 220 typedef struct {
 221   unsigned char header_data[COAP_TCP_HEADER_NO_FIELD];
 222   unsigned char token[]; /* the actual token, if any */
 223 } coap_hdr_tcp_t;
 224
 225 typedef struct {
 226   unsigned char header_data[COAP_TCP_HEADER_8_BIT];
 227   unsigned char token[]; /* the actual token, if any */
 228 } coap_hdr_tcp_8bit_t;
 229
 230 typedef struct {
 231   unsigned char header_data[COAP_TCP_HEADER_16_BIT];
 232   unsigned char token[]; /* the actual token, if any */
 233 } coap_hdr_tcp_16bit_t;
 234
 235 typedef struct {
 236   unsigned char header_data[6];
 237   unsigned char token[]; /* the actual token, if any */
 238 } coap_hdr_tcp_32bit_t;
 239
 240 typedef union {
 241   coap_hdr_udp_t udp;
 242   coap_hdr_tcp_t tcp;
 243   coap_hdr_tcp_8bit_t tcp_8bit;
 244   coap_hdr_tcp_16bit_t tcp_16bit;
 245   coap_hdr_tcp_32bit_t tcp_32bit;
 246 } coap_hdr_transport_t;
 247
 248 // Typedef for backwards compatibility.
 249 typedef coap_hdr_udp_t coap_hdr_t;
 250
 251 #define COAP_MESSAGE_IS_EMPTY(MSG)    ((MSG).code == 0)
 252 #define COAP_MESSAGE_IS_REQUEST(MSG)  (!COAP_MESSAGE_IS_EMPTY(MSG)  \
 253                        && ((MSG).code < 32))
 254 #define COAP_MESSAGE_IS_RESPONSE(MSG) ((MSG).code >= 64 && (MSG).code <= 191)
 255
 256 #define COAP_OPT_LONG 0x0F  /* OC == 0b1111 indicates that the option list
 257                              * in a CoAP message is limited by 0b11110000
 258                              * marker */
 259
 260 #define COAP_OPT_END 0xF0   /* end marker */
 261
 262 #define COAP_PAYLOAD_START 0xFF /* payload marker */
 263
 264 /**
 265  * Structures for more convenient handling of options. (To be used with ordered
 266  * coap_list_t.) The option's data will be added to the end of the coap_option
 267  * structure (see macro COAP_OPTION_DATA).
 268  */
 269 typedef struct {
 270     unsigned short key; /* the option key (no delta coding) */
 271     unsigned int length;
 272 } coap_option;
 273
 274 #define COAP_OPTION_KEY(option) (option).key
 275 #define COAP_OPTION_LENGTH(option) (option).length
 276 #define COAP_OPTION_DATA(option) ((unsigned char *)&(option) + sizeof(coap_option))
 277
 278 /**
 279  * Header structure for CoAP PDUs
 280  */
 281
 282 typedef struct {
 283     size_t max_size; /**< allocated storage for options and data */
 284
 285     union {
 286         coap_hdr_t *hdr;          /**< Address of the first byte of the CoAP message.
 287                                    *   This may or may not equal (coap_hdr_t*)(pdu+1)
 288                                    *   depending on the memory management
 289                                    *   implementation. */
 290         coap_hdr_transport_t *transport_hdr; /**< Address of the first byte of the CoAP message.
 291                                                *   This may or may not equal (coap_hdr_t*)(pdu+1)
 292                                                *   depending on the memory management
 293                                                *   implementation. */
 294     };
 295     unsigned short max_delta; /**< highest option number */
 296     unsigned int length; /**< PDU length (including header, options, data)  */
 297     unsigned char *data; /**< payload */
 298
 299 #ifdef WITH_LWIP
 300     struct pbuf *pbuf;        /**< lwIP PBUF. The package data will always reside
 301                                *    inside the pbuf's payload, but this pointer
 302                                *    has to be kept because no exact offset can be
 303                                *    given. This field must not be accessed from
 304                                *    outside, because the pbuf's reference count
 305                                *    is checked to be 1 when the pbuf is assigned
 306                                *    to the pdu, and the pbuf stays exclusive to
 307                                *    this pdu. */
 308 #endif
 309
 310 } coap_pdu_t;
 311
 312 /**
 313  * Options in coap_pdu_t are accessed with the macro COAP_OPTION.
 314  */
 315 #define COAP_OPTION(node) ((coap_option *)(node)->options)
 316 #ifdef __cplusplus
 317 extern "C"
 318 {
 319 #endif
 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, for having enough head space for
 326  * the PDU struct (which is located directly in front of the data, overwriting
 327  * the old other headers), and for having only one reference. The reference is
 328  * stored in the PDU and will be freed when the PDU is freed.
 329  *
 330  * (For now, these are fatal errors; in future, a new pbuf might be allocated,
 331  * the data copied and the passed pbuf freed).
 332  *
 333  * This behaves like coap_pdu_init(0, 0, 0, pbuf->tot_len), and afterwards
 334  * copying the contents of the pbuf to the pdu.
 335  *
 336  * @return A pointer to the new PDU object or @c NULL on error.
 337  */
 338 coap_pdu_t * coap_pdu_from_pbuf(struct pbuf *pbuf);
 339 #endif
 340
 341 /**
 342  * Creates a new CoAP PDU of given @p size (must be large enough to hold the
 343  * basic CoAP message header (coap_hdr_t). The function returns a pointer to the
 344  * node coap_pdu_t object on success, or @c NULL on error. The storage allocated
 345  * for the result must be released with coap_delete_pdu().
 346  *
 347  * @param type The type of the PDU (one of COAP_MESSAGE_CON, COAP_MESSAGE_NON,
 348  *             COAP_MESSAGE_ACK, COAP_MESSAGE_RST).
 349  * @param code The message code.
 350  * @param id   The message id to set or COAP_INVALID_TID if unknown.
 351  * @param size The number of bytes to allocate for the actual message.
 352  *
 353  * @return A pointer to the new PDU object or @c NULL on error.
 354  */
 355 coap_pdu_t *
 356 coap_pdu_init(unsigned char type,
 357               unsigned char code,
 358               unsigned short id,
 359               size_t size);
 360
 361 /**
 362  * Creates a new CoAP PDU of given @p size (must be large enough to hold the
 363  * basic CoAP message header (coap_hdr_t). The function returns a pointer to
 364  * the node coap_pdu_t object on success, or @c NULL on error. The storage
 365  * allocated for the result must be released with coap_delete_pdu().
 366  *
 367  * @param type The type of the PDU (one of COAP_MESSAGE_CON,
 368  *             COAP_MESSAGE_NON, COAP_MESSAGE_ACK, COAP_MESSAGE_RST).
 369  * @param code The message code.
 370  * @param id   The message id to set or COAP_INVALID_TID if unknown.
 371  * @param size The number of bytes to allocate for the actual message.
 372  * @param transport The transport type.
 373  *
 374  * @return A pointer to the new PDU object or @c NULL on error.
 375  */
 376 coap_pdu_t *
 377 coap_pdu_init2(unsigned char type, unsigned char code, unsigned short id,
 378                size_t size, coap_transport_t transport);
 379
 380 /**
 381  * Clears any contents from @p pdu and resets @c version field, @c
 382  * length and @c data pointers. @c max_size is set to @p size, any
 383  * other field is set to @c 0. Note that @p pdu must be a valid
 384  * pointer to a coap_pdu_t object created e.g. by coap_pdu_init().
 385  */
 386 void coap_pdu_clear(coap_pdu_t *pdu, size_t size);
 387
 388 /**
 389  * Clears any contents from @p pdu and resets @c version field, @c
 390  * length and @c data pointers. @c max_size is set to @p size, any
 391  * other field is set to @c 0. Note that @p pdu must be a valid
 392  * pointer to a coap_pdu_t object created e.g. by coap_pdu_init().
 393  */
 394 void coap_pdu_clear2(coap_pdu_t *pdu, size_t size, coap_transport_t transport,
 395                      unsigned int length);
 396
 397 /**
 398  * Creates a new CoAP PDU.
 399  * The object is created on the heap and must be released using
 400  * coap_delete_pdu();
 401  *
 402  * @deprecated This function allocates the maximum storage for each
 403  * PDU. Use coap_pdu_init() instead.
 404  */
 405 coap_pdu_t *coap_new_pdu(void);
 406
 407 /**
 408  * Creates a new CoAP PDU. The object is created on the heap and must be released
 409  * using coap_delete_pdu();
 410  *
 411  * @deprecated This function allocates the maximum storage for each
 412  * PDU. Use coap_pdu_init2() instead.
 413  */
 414 coap_pdu_t *coap_new_pdu2(coap_transport_t transport, unsigned int size);
 415
 416 void coap_delete_pdu(coap_pdu_t *);
 417
 418 /**
 419  * Parses @p data into the CoAP PDU structure given in @p result.
 420  * This function returns @c 0 on error or a number greater than zero on success.
 421  *
 422  * @param data   The raw data to parse as CoAP PDU
 423  * @param length The actual size of @p data
 424  * @param result The PDU structure to fill. Note that the structure must
 425  *               provide space for at least @p length bytes to hold the
 426  *               entire CoAP PDU.
 427  *
 428  * @return A value greater than zero on success or @c 0 on error.
 429  */
 430 int coap_pdu_parse(unsigned char *data,
 431                    size_t length,
 432                    coap_pdu_t *result);
 433
 434 /**
 435  * Parses @p data into the CoAP PDU structure given in @p result.
 436  * This function returns @c 0 on error or a number greater than zero on success.
 437  *
 438  * @param data   The raw data to parse as CoAP PDU
 439  * @param length The actual size of @p data
 440  * @param result The PDU structure to fill. Note that the structure must
 441  *               provide space for at least @p length bytes to hold the
 442  *               entire CoAP PDU.
 443  * @param transport The transport type.
 444  * @return A value greater than zero on success or @c 0 on error.
 445  */
 446 int coap_pdu_parse2(unsigned char *data, size_t length, coap_pdu_t *pdu,
 447                     coap_transport_t transport);
 448
 449 #ifdef WITH_TCP
 450 /**
 451  * Get total pdu size including header + option + payload (with marker) from pdu data.
 452  *
 453  * @param data   The raw data to parse as CoAP PDU.
 454  * @param size   payload size of pdu.
 455  * @return Total message length.
 456  */
 457 size_t coap_get_total_message_length(const unsigned char *data, size_t size);
 458
 459 /**
 460  * Get transport type of coap header for coap over tcp
 461  * through payload size(including payload marker) + option size.
 462  *
 463  * @param size   payload size of pdu.
 464  * @return The transport type.
 465  */
 466 coap_transport_t coap_get_tcp_header_type_from_size(unsigned int size);
 467
 468 /**
 469  * Get transport type of coap header for coap over tcp
 470  * through first nibble(0~E) of init-byte .
 471  *
 472  * @param legnth   length value of init byte.
 473 * @return The transport type.
 474  */
 475 coap_transport_t coap_get_tcp_header_type_from_initbyte(unsigned int length);
 476
 477 /**
 478  * Add length of option/payload into 'Len+ byte...' field of coap header
 479  * for coap over tcp.
 480  *
 481  * @param pdu  The pdu pointer.
 482  * @param transport The transport type.
 483  * @param length  length value of init byte.
 484  */
 485 void coap_add_length(const coap_pdu_t *pdu, coap_transport_t transport,
 486                      unsigned int length);
 487
 488 /**
 489  * Get the length of option/payload field of coap header for coap over tcp.
 490  *
 491  * @param pdu  The pdu pointer.
 492  * @param transport The transport type.
 493  * @return length value of init byte.
 494  */
 495 unsigned int coap_get_length(const coap_pdu_t *pdu, coap_transport_t transport);
 496
 497 /**
 498  * Get the length of option/payload field of coap header for coap over tcp.
 499  *
 500  * @param header   The header to parse.
 501  * @return transport The transport type.
 502  */
 503 unsigned int coap_get_length_from_header(const unsigned char *header,
 504                                          coap_transport_t transport);
 505
 506 /**
 507  * Get length of header including len, TKL, Len+bytes, Code, token bytes for coap over tcp.
 508  *
 509  * @param data   The raw data to parse as CoAP PDU
 510  * @return header length + token length
 511  */
 512 unsigned int coap_get_tcp_header_length(unsigned char *data);
 513
 514 /**
 515  * Get length of header including len, TKL, Len+bytes, Code
 516  * without token bytes for coap over tcp.
 517  *
 518  * @param transport The transport type.
 519  * @return header length.
 520  */
 521 unsigned int coap_get_tcp_header_length_for_transport(coap_transport_t transport);
 522
 523 /**
 524  * Get option length.
 525  *
 526  * @param key      delta of option
 527  * @param length   length of option
 528  * @return total option length
 529  */
 530 size_t coap_get_opt_header_length(unsigned short key, size_t length);
 531 #endif /* WITH_TCP */
 532
 533 /**
 534  * Add code in coap header.
 535  *
 536  * @param pdu  The pdu pointer.
 537  * @param transport The transport type.
 538  * @param code  The message code.
 539  */
 540 void coap_add_code(const coap_pdu_t *pdu, coap_transport_t transport,
 541                    unsigned int code);
 542
 543 /**
 544  * Get message code from coap header
 545  *
 546  * @param pdu  The pdu pointer.
 547  * @param transport The transport type.
 548  * @return The message code.
 549  */
 550 unsigned int coap_get_code(const coap_pdu_t *pdu, coap_transport_t transport);
 551
 552 /**
 553  * Adds token of length @p len to @p pdu.
 554  * Adding the token destroys any following contents of the pdu. Hence options
 555  * and data must be added after coap_add_token() has been called. In @p pdu,
 556  * length is set to @p len + @c 4, and max_delta is set to @c 0.  This funtion
 557  * returns @c 0 on error or a value greater than zero on success.
 558  *
 559  * @param pdu  The PDU where the token is to be added.
 560  * @param len  The length of the new token.
 561  * @param data The token to add.
 562  *
 563  * @return A value greater than zero on success, or @c 0 on error.
 564  */
 565 int coap_add_token(coap_pdu_t *pdu,
 566                    size_t len,
 567                    const unsigned char *data);
 568
 569 /**
 570  * Adds token of length @p len to @p pdu. Adding the token destroys
 571  * any following contents of the pdu. Hence options and data must be
 572  * added after coap_add_token2() has been called. In @p pdu, length is
 573  * set to @p len + @c 4, and max_delta is set to @c 0.  This funtion
 574  * returns @c 0 on error or a value greater than zero on success.
 575  *
 576  * @param pdu  The pdu pointer.
 577  * @param len  The length of the new token.
 578  * @param data The token to add.
 579  * @param transport The transport type.
 580  * @return A value greater than zero on success, or @c 0 on error.
 581  */
 582 int coap_add_token2(coap_pdu_t *pdu, size_t len, const unsigned char *data,
 583                     coap_transport_t transport);
 584
 585 /**
 586  * Get token from coap header
 587  *
 588  * @param pdu_hdr  The header pointer of PDU.
 589  * @param token  out parameter to get token.
 590  * @param token_length  out parameter to get token length.
 591  */
 592 void coap_get_token(const coap_hdr_t *pdu_hdr,
 593                     unsigned char **token, unsigned int *token_length);
 594
 595 /**
 596  * Get token from coap header based on transport type
 597  *
 598  * @param pdu_hdr  The header pointer of PDU.
 599  * @param transport The transport type.
 600  * @param token  out parameter to get token.
 601  * @param token_length  out parameter to get token length.
 602  */
 603 void coap_get_token2(const coap_hdr_transport_t *pdu_hdr, coap_transport_t transport,
 604                      unsigned char **token, unsigned int *token_length);
 605
 606 /**
 607  * Adds option of given type to pdu that is passed as first parameter.
 608  * coap_add_option() destroys the PDU's data, so coap_add_data() must be called
 609  * after all options have been added. As coap_add_token() destroys the options
 610  * following the token, the token must be added before coap_add_option() is
 611  * called. This function returns the number of bytes written or @c 0 on error.
 612  */
 613 size_t coap_add_option(coap_pdu_t *pdu,
 614                        unsigned short type,
 615                        unsigned int len,
 616                        const unsigned char *data);
 617
 618 /**
 619  * Adds option of given type to pdu that is passed as first
 620  * parameter. coap_add_option2() destroys the PDU's data, so
 621  * coap_add_data() must be called after all options have been added.
 622  * As coap_add_token2() destroys the options following the token,
 623  * the token must be added before coap_add_option2() is called.
 624  * This function returns the number of bytes written or @c 0 on error.
 625  */
 626 size_t coap_add_option2(coap_pdu_t *pdu, unsigned short type, unsigned int len,
 627                         const unsigned char *data, coap_transport_t transport);
 628
 629 /**
 630  * Adds option of given type to pdu that is passed as first parameter, but does
 631  * not write a value. It works like coap_add_option with respect to calling
 632  * sequence (i.e. after token and before data). This function returns a memory
 633  * address to which the option data has to be written before the PDU can be
 634  * sent, or @c NULL on error.
 635  */
 636 unsigned char *coap_add_option_later(coap_pdu_t *pdu,
 637                                      unsigned short type,
 638                                      unsigned int len);
 639
 640 /**
 641  * Adds given data to the pdu that is passed as first parameter. Note that the
 642  * PDU's data is destroyed by coap_add_option(). coap_add_data() must be called
 643  * only once per PDU, otherwise the result is undefined.
 644  */
 645 int coap_add_data(coap_pdu_t *pdu,
 646                   unsigned int len,
 647                   const unsigned char *data);
 648
 649 /**
 650  * Retrieves the length and data pointer of specified PDU. Returns 0 on error or
 651  * 1 if *len and *data have correct values. Note that these values are destroyed
 652  * with the pdu.
 653  */
 654 int coap_get_data(const coap_pdu_t *pdu,
 655                   size_t *len,
 656                   unsigned char **data);
 657 #ifdef __cplusplus
 658 } /* extern "C" */
 659 #endif
 660 #endif /* _COAP_PDU_H_ */