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