resource/csdk/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 #ifdef __cplusplus
  13 extern "C" {
  14 #endif
  15
  16 #include "config.h"
  17 #include "coap_list.h"
  18 #include "uri.h"
  19
  20 #ifdef WITH_LWIP
  21 #include <lwip/pbuf.h>
  22 #endif
  23
  24 /* pre-defined constants that reflect defaults for CoAP */
  25 // This value is based on the DEFAULT_LEISURE (5 seconds) defined in RFC 7252
  26 #define MAX_MULTICAST_DELAY_SEC (5)
  27
  28 /* response timeout in seconds, this can not be less that the delays between calls to OCProcess*/
  29 #define COAP_DEFAULT_RESPONSE_TIMEOUT  2
  30 #define COAP_DEFAULT_MAX_RETRANSMIT    4 /* max number of retransmissions */
  31 #define COAP_DEFAULT_PORT           5683 /* CoAP default UDP port */
  32 #define COAP_DEFAULT_MAX_AGE          60 /* default maximum object lifetime in seconds */
  33 #ifndef COAP_MAX_PDU_SIZE
  34 #ifdef WITH_ARDUINO
  35 #define COAP_MAX_PDU_SIZE           320 /* maximum size of a CoAP PDU for embedded platforms*/
  36 #else
  37 #define COAP_MAX_PDU_SIZE           1400 /* maximum size of a CoAP PDU for big platforms*/
  38 #endif
  39 #endif /* COAP_MAX_PDU_SIZE */
  40
  41 #define COAP_DEFAULT_VERSION           1 /* version of CoAP supported */
  42 #define COAP_DEFAULT_SCHEME        "coap" /* the default scheme for CoAP URIs */
  43
  44 /** well-known resources URI */
  45 #define COAP_DEFAULT_URI_WELLKNOWN ".well-known/core"
  46
  47 #ifdef __COAP_DEFAULT_HASH
  48 /* pre-calculated hash key for the default well-known URI */
  49 #define COAP_DEFAULT_WKC_HASHKEY   "\345\130\144\245"
  50 #endif
  51
  52 /* CoAP message types */
  53
  54 #define COAP_MESSAGE_CON               0 /* confirmable message (requires ACK/RST) */
  55 #define COAP_MESSAGE_NON               1 /* non-confirmable message (one-shot message) */
  56 #define COAP_MESSAGE_ACK               2 /* used to acknowledge confirmable messages */
  57 #define COAP_MESSAGE_RST               3 /* indicates error in received messages */
  58
  59 /* CoAP request methods */
  60
  61 #define COAP_REQUEST_GET       1
  62 #define COAP_REQUEST_POST      2
  63 #define COAP_REQUEST_PUT       3
  64 #define COAP_REQUEST_DELETE    4
  65
  66 /* CoAP option types (be sure to update check_critical when adding options */
  67
  68 #define COAP_OPTION_IF_MATCH      1 /* C, opaque, 0-8 B, (none) */
  69 #define COAP_OPTION_URI_HOST      3 /* C, String, 1-255 B, destination address */
  70 #define COAP_OPTION_ETAG          4 /* E, opaque, 1-8 B, (none) */
  71 #define COAP_OPTION_IF_NONE_MATCH 5 /* empty, 0 B, (none) */
  72 #define COAP_OPTION_URI_PORT      7 /* C, uint, 0-2 B, destination port */
  73 #define COAP_OPTION_LOCATION_PATH 8 /* E, String, 0-255 B, - */
  74 #define COAP_OPTION_URI_PATH     11 /* C, String, 0-255 B, (none) */
  75 #define COAP_OPTION_CONTENT_FORMAT 12 /* E, uint, 0-2 B, (none) */
  76 #define COAP_OPTION_CONTENT_TYPE COAP_OPTION_CONTENT_FORMAT
  77 #define COAP_OPTION_MAXAGE       14 /* E, uint, 0--4 B, 60 Seconds */
  78 #define COAP_OPTION_URI_QUERY    15 /* C, String, 1-255 B, (none) */
  79 #define COAP_OPTION_ACCEPT       17 /* C, uint,   0-2 B, (none) */
  80 #define COAP_OPTION_LOCATION_QUERY 20 /* E, String,   0-255 B, (none) */
  81 #define COAP_OPTION_PROXY_URI    35 /* C, String, 1-1034 B, (none) */
  82 #define COAP_OPTION_PROXY_SCHEME 39 /* C, String, 1-255 B, (none) */
  83 #define COAP_OPTION_SIZE2        28 /* E, uint, 0-4 B, (none) */
  84 #define COAP_OPTION_SIZE1        60 /* E, uint, 0-4 B, (none) */
  85
  86 /* option types from draft-ietf-coap-observe-09 */
  87
  88 #define COAP_OPTION_OBSERVE       6 /* E, empty/uint, 0 B/0-3 B, (none) */
  89 #define COAP_OPTION_SUBSCRIPTION  COAP_OPTION_OBSERVE
  90
  91 /* selected option types from draft-core-block-04 */
  92
  93 #define COAP_OPTION_BLOCK2       23 /* C, uint, 0--3 B, (none) */
  94 #define COAP_OPTION_BLOCK1       27 /* C, uint, 0--3 B, (none) */
  95
  96 #define COAP_VENDOR_OPT_START    (2048)
  97 /**< the highest option number we know
  98  * COAP_MAX_OPT has to be larger than COAP_VENDOR_OPT_START
  99  * however, we should keep in mind that COAP_MAX_OPT
 100  * impacts the size of option filter as its size is about
 101  * ceil(COAP_MAX_OPT>>3)
 102  * Default is 3000 (just a nice round number)
 103  */
 104 #define COAP_MAX_OPT             (3000)
 105
 106 /* CoAP result codes (HTTP-Code / 100 * 40 + HTTP-Code % 100) */
 107
 108 /* As of draft-ietf-core-coap-04, response codes are encoded to base
 109  * 32, i.e.  the three upper bits determine the response class while
 110  * the remaining five fine-grained information specific to that class.
 111  */
 112 #define COAP_RESPONSE_CODE(N) (((N)/100 << 5) | (N)%100)
 113
 114 /* Determines the class of response code C */
 115 #define COAP_RESPONSE_CLASS(C) (((C) >> 5) & 0xFF)
 116
 117 #ifndef SHORT_ERROR_RESPONSE
 118 /**
 119  * Returns a human-readable response phrase for the specified CoAP
 120  * response @p code. This function returns @c NULL if not found.
 121  *
 122  * @param code The response code for which the literal phrase should
 123  * be retrieved.
 124  *
 125  * @return A zero-terminated string describing the error, or @c NULL
 126  * if not found.
 127  */
 128 const char *coap_response_phrase(unsigned char code);
 129
 130 #define COAP_ERROR_PHRASE_LENGTH 32 /**< maximum length of error phrase */
 131
 132 #else
 133 #define coap_response_phrase(x) ((char *)NULL)
 134
 135 #define COAP_ERROR_PHRASE_LENGTH 0 /**< maximum length of error phrase */
 136 #endif /* SHORT_ERROR_RESPONSE */
 137
 138 /* The following definitions exist for backwards compatibility */
 139 #if 0 /* this does not exist any more */
 140 #define COAP_RESPONSE_100      40 /* 100 Continue */
 141 #endif
 142 #define COAP_RESPONSE_200      COAP_RESPONSE_CODE(200)  /* 2.00 OK */
 143 #define COAP_RESPONSE_201      COAP_RESPONSE_CODE(201)  /* 2.01 Created */
 144 #define COAP_RESPONSE_202      COAP_RESPONSE_CODE(202)  /* 2.02 Deleted */
 145 #define COAP_RESPONSE_304      COAP_RESPONSE_CODE(203)  /* 2.03 Valid */
 146 #define COAP_RESPONSE_400      COAP_RESPONSE_CODE(400)  /* 4.00 Bad Request */
 147 #define COAP_RESPONSE_403      COAP_RESPONSE_CODE(403)  /* 4.03 Forbidden */
 148 #define COAP_RESPONSE_404      COAP_RESPONSE_CODE(404)  /* 4.04 Not Found */
 149 #define COAP_RESPONSE_405      COAP_RESPONSE_CODE(405)  /* 4.05 Method Not Allowed */
 150 #define COAP_RESPONSE_415      COAP_RESPONSE_CODE(415)  /* 4.15 Unsupported Media Type */
 151 #define COAP_RESPONSE_500      COAP_RESPONSE_CODE(500)  /* 5.00 Internal Server Error */
 152 #define COAP_RESPONSE_501      COAP_RESPONSE_CODE(501)  /* 5.01 Not Implemented */
 153 #define COAP_RESPONSE_503      COAP_RESPONSE_CODE(503)  /* 5.03 Service Unavailable */
 154 #define COAP_RESPONSE_504      COAP_RESPONSE_CODE(504)  /* 5.04 Gateway Timeout */
 155 #if 0  /* these response codes do not have a valid code any more */
 156 #  define COAP_RESPONSE_X_240    240   /* Token Option required by server */
 157 #  define COAP_RESPONSE_X_241    241   /* Uri-Authority Option required by server */
 158 #endif
 159 #define COAP_RESPONSE_X_242    COAP_RESPONSE_CODE(402)  /* Critical Option not supported */
 160
 161 /* CoAP media type encoding */
 162
 163 #define COAP_MEDIATYPE_TEXT_PLAIN                     0 /* text/plain (UTF-8) */
 164 #define COAP_MEDIATYPE_APPLICATION_LINK_FORMAT       40 /* application/link-format */
 165 #define COAP_MEDIATYPE_APPLICATION_XML               41 /* application/xml */
 166 #define COAP_MEDIATYPE_APPLICATION_OCTET_STREAM      42 /* application/octet-stream */
 167 #define COAP_MEDIATYPE_APPLICATION_RDF_XML           43 /* application/rdf+xml */
 168 #define COAP_MEDIATYPE_APPLICATION_EXI               47 /* application/exi  */
 169 #define COAP_MEDIATYPE_APPLICATION_JSON              50 /* application/json  */
 170
 171 /* Note that identifiers for registered media types are in the range 0-65535. We
 172  * use an unallocated type here and hope for the best. */
 173 #define COAP_MEDIATYPE_ANY                         0xff /* any media type */
 174
 175 /* CoAP transaction id */
 176 /*typedef unsigned short coap_tid_t; */
 177 typedef int coap_tid_t;
 178 #define COAP_INVALID_TID -1
 179
 180 #if defined(__GNUC__) && !defined(__clang__) && !defined(__INTEL_COMPILER)
 181 #pragma GCC diagnostic push
 182 #pragma GCC diagnostic ignored "-pedantic"
 183 #endif
 184 #ifdef WORDS_BIGENDIAN
 185 typedef struct {
 186   unsigned int version:2;       /* protocol version */
 187   unsigned int type:2;          /* type flag */
 188   unsigned int token_length:4;  /* length of Token */
 189   unsigned int code:8;          /* request method (value 1--10) or response code (value 40-255) */
 190   unsigned short id;            /* message id */
 191   __extension__ unsigned char token[0]; /* the actual token, if any */
 192 } coap_hdr_t;
 193 #else
 194 typedef struct {
 195   unsigned int token_length:4;  /* length of Token */
 196   unsigned int type:2;          /* type flag */
 197   unsigned int version:2;       /* protocol version */
 198   unsigned int code:8;          /* request method (value 1--10) or response code (value 40-255) */
 199   unsigned short id;            /* transaction id (network byte order!) */
 200   __extension__ unsigned char token[0]; /* the actual token, if any */
 201 } coap_hdr_t;
 202 #endif
 203 #if defined(__GNUC__) && !defined(__clang__) && !defined(__INTEL_COMPILER)
 204 #pragma GCC diagnostic pop
 205 #endif
 206
 207 #define COAP_MESSAGE_IS_EMPTY(MSG)    ((MSG)->code == 0)
 208 #define COAP_MESSAGE_IS_REQUEST(MSG)  (!COAP_MESSAGE_IS_EMPTY(MSG)      \
 209                                        && ((MSG)->code < 32))
 210 #define COAP_MESSAGE_IS_RESPONSE(MSG) ((MSG)->code >= 64 && (MSG)->code <= 191)
 211
 212 #define COAP_OPT_LONG 0x0F      /* OC == 0b1111 indicates that the option list in a
 213                                  * CoAP message is limited by 0b11110000 marker */
 214
 215 #define COAP_OPT_END 0xF0       /* end marker */
 216
 217 #define COAP_PAYLOAD_START 0xFF /* payload marker */
 218
 219 /**
 220  * Structures for more convenient handling of options. (To be used with ordered
 221  * coap_list_t.) The option's data will be added to the end of the coap_option
 222  * structure (see macro COAP_OPTION_DATA).
 223  */
 224 typedef struct {
 225   unsigned short key;           /* the option key (no delta coding) */
 226   unsigned int length;
 227 } coap_option;
 228
 229 #define COAP_OPTION_KEY(option) (option).key
 230 #define COAP_OPTION_LENGTH(option) (option).length
 231 #define COAP_OPTION_DATA(option) ((unsigned char *)&(option) + sizeof(coap_option))
 232
 233 /** Header structure for CoAP PDUs */
 234
 235 typedef struct {
 236   size_t max_size;      /**< allocated storage for options and data */
 237
 238   coap_hdr_t *hdr;
 239   unsigned short max_delta;     /**< highest option number */
 240   unsigned short length;        /**< PDU length (including header, options, data)  */
 241   unsigned char *data;          /**< payload */
 242
 243 #ifdef WITH_LWIP
 244   struct pbuf *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. */
 245 #endif
 246
 247 } coap_pdu_t;
 248
 249 /** Options in coap_pdu_t are accessed with the macro COAP_OPTION. */
 250 #define COAP_OPTION(node) ((coap_option *)(node)->options)
 251
 252 #ifdef WITH_LWIP
 253 /**
 254  * Creates a CoAP PDU from an lwIP @p pbuf, whose reference is passed on to
 255  * this function.
 256  *
 257  * The pbuf is checked for being contiguous, for having enough head space for
 258  * the PDU struct (which is located directly in front of the data, overwriting
 259  * the old other headers), and for having only one reference. The reference is
 260  * stored in the PDU and will be freed when the PDU is freed.
 261  *
 262  * (For now, these are errors; in future, a new pbuf might be allocated, the
 263  * data copied and the passed pbuf freed).
 264  *
 265  * This behaves like coap_pdu_init(0, 0, 0, pbuf->tot_len), and afterwards
 266  * copying the contents of the pbuf to the pdu.
 267  *
 268  * @return A pointer to the new PDU object or @c NULL on error.
 269  */
 270 coap_pdu_t * coap_pdu_from_pbuf(struct pbuf *pbuf);
 271 #endif
 272
 273 /**
 274  * Creates a new CoAP PDU of given @p size (must be large enough to hold the
 275  * basic CoAP message header (coap_hdr_t). The function returns a pointer to
 276  * the node coap_pdu_t object on success, or @c NULL on error. The storage
 277  * allocated for the result must be released with coap_delete_pdu().
 278  *
 279  * @param type The type of the PDU (one of COAP_MESSAGE_CON,
 280  *             COAP_MESSAGE_NON, COAP_MESSAGE_ACK, COAP_MESSAGE_RST).
 281  * @param code The message code.
 282  * @param id   The message id to set or COAP_INVALID_TID if unknown.
 283  * @param size The number of bytes to allocate for the actual message.
 284  *
 285  * @return A pointer to the new PDU object or @c NULL on error.
 286  */
 287 coap_pdu_t *
 288 coap_pdu_init(unsigned char type, unsigned char code,
 289               unsigned short id, size_t size);
 290
 291 /**
 292  * Clears any contents from @p pdu and resets @c version field, @c
 293  * length and @c data pointers. @c max_size is set to @p size, any
 294  * other field is set to @c 0. Note that @p pdu must be a valid
 295  * pointer to a coap_pdu_t object created e.g. by coap_pdu_init().
 296  */
 297 void coap_pdu_clear(coap_pdu_t *pdu, size_t size);
 298
 299 /**
 300  * Creates a new CoAP PDU. The object is created on the heap and must be released
 301  * using coap_delete_pdu();
 302  *
 303  * @deprecated This function allocates the maximum storage for each
 304  * PDU. Use coap_pdu_init() instead.
 305  */
 306 coap_pdu_t *coap_new_pdu();
 307
 308 void coap_delete_pdu(coap_pdu_t *);
 309
 310 /**
 311  * Parses @p data into the CoAP PDU structure given in @p result. This
 312  * function returns @c 0 on error or a number greater than zero on
 313  * success.
 314  *
 315  * @param data   The raw data to parse as CoAP PDU
 316  * @param length The actual size of @p data
 317  * @param result The PDU structure to fill. Note that the structure must
 318  *               provide space for at least @p length bytes to hold the
 319  *               entire CoAP PDU.
 320  * @return A value greater than zero on success or @c 0 on error.
 321  */
 322 int coap_pdu_parse(unsigned char *data, size_t length, coap_pdu_t *result);
 323
 324 /**
 325  * Adds token of length @p len to @p pdu. Adding the token destroys
 326  * any following contents of the pdu. Hence options and data must be
 327  * added after coap_add_token() has been called. In @p pdu, length is
 328  * set to @p len + @c 4, and max_delta is set to @c 0.  This funtion
 329  * returns @c 0 on error or a value greater than zero on success.
 330  *
 331  * @param pdu  The PDU where the token is to be added.
 332  * @param len  The length of the new token.
 333  * @param data The token to add.
 334  * @return A value greater than zero on success, or @c 0 on error.
 335  */
 336 int coap_add_token(coap_pdu_t *pdu, size_t len, const unsigned char *data);
 337
 338 /**
 339  * Adds option of given type to pdu that is passed as first
 340  * parameter. coap_add_option() destroys the PDU's data, so
 341  * coap_add_data() must be called after all options have been added.
 342  * As coap_add_token() destroys the options following the token,
 343  * the token must be added before coap_add_option() is called.
 344  * This function returns the number of bytes written or @c 0 on error.
 345  */
 346 size_t coap_add_option(coap_pdu_t *pdu, unsigned short type,
 347                        unsigned int len, const unsigned char *data);
 348
 349 /**
 350  * Adds option of given type to pdu that is passed as first
 351  * parameter, but does not write a value. It works like coap_add_option with
 352  * respect to calling sequence (i.e. after token and before data).
 353  * This function returns a memory address to which the option data has to be
 354  * written before the PDU can be sent, or @c NULL on error.
 355  */
 356 unsigned char *coap_add_option_later(coap_pdu_t *pdu, unsigned short type,
 357                                      unsigned int len);
 358
 359 /**
 360  * Adds given data to the pdu that is passed as first parameter. Note
 361  * that the PDU's data is destroyed by coap_add_option(). coap_add_data()
 362  * must be called only once per PDU, otherwise the result is undefined.
 363  */
 364 int coap_add_data(coap_pdu_t *pdu, unsigned int len, const unsigned char *data);
 365
 366 /**
 367  * Retrieves the length and data pointer of specified PDU. Returns 0 on error
 368  * or 1 if *len and *data have correct values. Note that these values are
 369  * destroyed with the pdu.
 370  */
 371 int coap_get_data(coap_pdu_t *pdu, size_t *len, unsigned char **data);
 372
 373 #ifdef __cplusplus
 374 }
 375 #endif
 376
 377 #endif /* _PDU_H_ */