1 /* pdu.h -- CoAP message structure
3 * Copyright (C) 2010--2012 Olaf Bergmann <bergmann@tzi.org>
5 * This file is part of the CoAP library libcoap. Please see
6 * README for terms of use.
13 #include "coap_list.h"
17 #include <lwip/pbuf.h>
20 /* pre-defined constants that reflect defaults for CoAP */
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
28 #define COAP_MAX_PDU_SIZE 320 /* maximum size of a CoAP PDU for embedded platforms*/
30 #define COAP_MAX_PDU_SIZE 1400 /* maximum size of a CoAP PDU for big platforms*/
32 #endif /* COAP_MAX_PDU_SIZE */
34 #define COAP_DEFAULT_VERSION 1 /* version of CoAP supported */
35 #define COAP_DEFAULT_SCHEME "coap" /* the default scheme for CoAP URIs */
37 /** well-known resources URI */
38 #define COAP_DEFAULT_URI_WELLKNOWN ".well-known/core"
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"
45 /* CoAP message types */
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 */
52 /* CoAP request methods */
54 #define COAP_REQUEST_GET 1
55 #define COAP_REQUEST_POST 2
56 #define COAP_REQUEST_PUT 3
57 #define COAP_REQUEST_DELETE 4
59 /* CoAP option types (be sure to update check_critical when adding options */
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) */
79 /* option types from draft-ietf-coap-observe-09 */
81 #define COAP_OPTION_OBSERVE 6 /* E, empty/uint, 0 B/0-3 B, (none) */
82 #define COAP_OPTION_SUBSCRIPTION COAP_OPTION_OBSERVE
84 /* selected option types from draft-core-block-04 */
86 #define COAP_OPTION_BLOCK2 23 /* C, uint, 0--3 B, (none) */
87 #define COAP_OPTION_BLOCK1 27 /* C, uint, 0--3 B, (none) */
89 #define COAP_MAX_OPT 63 /**< the highest option number we know */
91 /* CoAP result codes (HTTP-Code / 100 * 40 + HTTP-Code % 100) */
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.
97 #define COAP_RESPONSE_CODE(N) (((N)/100 << 5) | (N)%100)
99 /* Determines the class of response code C */
100 #define COAP_RESPONSE_CLASS(C) (((C) >> 5) & 0xFF)
102 #ifndef SHORT_ERROR_RESPONSE
104 * Returns a human-readable response phrase for the specified CoAP
105 * response @p code. This function returns @c NULL if not found.
107 * @param code The response code for which the literal phrase should
110 * @return A zero-terminated string describing the error, or @c NULL
113 char *coap_response_phrase(unsigned char code);
115 #define COAP_ERROR_PHRASE_LENGTH 32 /**< maximum length of error phrase */
118 #define coap_response_phrase(x) ((char *)NULL)
120 #define COAP_ERROR_PHRASE_LENGTH 0 /**< maximum length of error phrase */
121 #endif /* SHORT_ERROR_RESPONSE */
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 */
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 */
142 #define COAP_RESPONSE_X_242 COAP_RESPONSE_CODE(402) /* Critical Option not supported */
144 /* CoAP media type encoding */
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 */
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 */
159 /* CoAP transaction id */
160 /*typedef unsigned short coap_tid_t; */
161 typedef int coap_tid_t;
162 #define COAP_INVALID_TID -1
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
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
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
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
181 #define COAP_OPTION_FIELD_8_BIT 12
182 #define COAP_OPTION_FIELD_16_BIT 256
183 #define COAP_OPTION_FIELD_32_BIT 65536
192 } coap_transport_type;
194 #ifdef WORDS_BIGENDIAN
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 */
209 unsigned char header_data[COAP_TCP_HEADER_NO_FIELD];
210 unsigned char token[]; /* the actual token, if any */
215 unsigned char header_data[COAP_TCP_HEADER_8_BIT];
216 unsigned char token[]; /* the actual token, if any */
217 } coap_hdr_tcp_8bit_t;
221 unsigned char header_data[COAP_TCP_HEADER_16_BIT];
222 unsigned char token[]; /* the actual token, if any */
223 } coap_hdr_tcp_16bit_t;
227 unsigned char header_data[6];
228 unsigned char token[]; /* the actual token, if any */
229 } coap_hdr_tcp_32bit_t;
237 unsigned int token_length :4; /* length of Token */
238 unsigned int type :2; /* type flag */
239 unsigned int version :2; /* protocol version */
240 unsigned int code :8; /* request method (value 1--10) or response code (value 40-255) */
241 unsigned short id; /* transaction id (network byte order!) */
242 unsigned char token[]; /* the actual token, if any */
247 unsigned char header_data[COAP_TCP_HEADER_NO_FIELD];
248 unsigned char token[]; /* the actual token, if any */
253 unsigned char header_data[COAP_TCP_HEADER_8_BIT];
254 unsigned char token[]; /* the actual token, if any */
255 } coap_hdr_tcp_8bit_t;
259 unsigned char header_data[COAP_TCP_HEADER_16_BIT];
260 unsigned char token[]; /* the actual token, if any */
261 } coap_hdr_tcp_16bit_t;
265 unsigned char header_data[COAP_TCP_HEADER_32_BIT];
266 unsigned char token[]; /* the actual token, if any */
267 } coap_hdr_tcp_32bit_t;
272 #define COAP_MESSAGE_IS_EMPTY(MSG) ((MSG).code == 0)
273 #define COAP_MESSAGE_IS_REQUEST(MSG) (!COAP_MESSAGE_IS_EMPTY(MSG) \
274 && ((MSG).code < 32))
275 #define COAP_MESSAGE_IS_RESPONSE(MSG) ((MSG).code >= 64 && (MSG).code <= 191)
277 #define COAP_OPT_LONG 0x0F /* OC == 0b1111 indicates that the option list in a
278 * CoAP message is limited by 0b11110000 marker */
280 #define COAP_OPT_END 0xF0 /* end marker */
282 #define COAP_PAYLOAD_START 0xFF /* payload marker */
285 * Structures for more convenient handling of options. (To be used with ordered
286 * coap_list_t.) The option's data will be added to the end of the coap_option
287 * structure (see macro COAP_OPTION_DATA).
291 unsigned short key; /* the option key (no delta coding) */
295 #define COAP_OPTION_KEY(option) (option).key
296 #define COAP_OPTION_LENGTH(option) (option).length
297 #define COAP_OPTION_DATA(option) ((unsigned char *)&(option) + sizeof(coap_option))
299 /** Header structure for CoAP PDUs */
303 size_t max_size; /**< allocated storage for options and data */
306 unsigned short max_delta; /**< highest option number */
307 unsigned int length; /**< PDU length (including header, options, data) */
308 unsigned char *data; /**< payload */
312 *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. */
317 /** Options in coap_pdu_t are accessed with the macro COAP_OPTION. */
318 #define COAP_OPTION(node) ((coap_option *)(node)->options)
325 * Creates a CoAP PDU from an lwIP @p pbuf, whose reference is passed on to
328 * The pbuf is checked for being contiguous, for having enough head space for
329 * the PDU struct (which is located directly in front of the data, overwriting
330 * the old other headers), and for having only one reference. The reference is
331 * stored in the PDU and will be freed when the PDU is freed.
333 * (For now, these are errors; in future, a new pbuf might be allocated, the
334 * data copied and the passed pbuf freed).
336 * This behaves like coap_pdu_init(0, 0, 0, pbuf->tot_len), and afterwards
337 * copying the contents of the pbuf to the pdu.
339 * @return A pointer to the new PDU object or @c NULL on error.
341 coap_pdu_t * coap_pdu_from_pbuf(struct pbuf *pbuf);
345 * Creates a new CoAP PDU of given @p size (must be large enough to hold the
346 * basic CoAP message header (coap_hdr_t). The function returns a pointer to
347 * the node coap_pdu_t object on success, or @c NULL on error. The storage
348 * allocated for the result must be released with coap_delete_pdu().
350 * @param type The type of the PDU (one of COAP_MESSAGE_CON,
351 * COAP_MESSAGE_NON, COAP_MESSAGE_ACK, COAP_MESSAGE_RST).
352 * @param code The message code.
353 * @param id The message id to set or COAP_INVALID_TID if unknown.
354 * @param size The number of bytes to allocate for the actual message.
355 * @param transport The transport type.
357 * @return A pointer to the new PDU object or @c NULL on error.
360 coap_pdu_init(unsigned char type, unsigned char code, unsigned short id,
361 size_t size, coap_transport_type transport);
364 * Clears any contents from @p pdu and resets @c version field, @c
365 * length and @c data pointers. @c max_size is set to @p size, any
366 * other field is set to @c 0. Note that @p pdu must be a valid
367 * pointer to a coap_pdu_t object created e.g. by coap_pdu_init().
369 void coap_pdu_clear(coap_pdu_t *pdu, size_t size, coap_transport_type transport,
370 unsigned int length);
373 * Creates a new CoAP PDU. The object is created on the heap and must be released
374 * using coap_delete_pdu();
376 * @deprecated This function allocates the maximum storage for each
377 * PDU. Use coap_pdu_init() instead.
379 coap_pdu_t *coap_new_pdu(coap_transport_type transport, unsigned int size);
381 void coap_delete_pdu(coap_pdu_t *);
384 * Parses @p data into the CoAP PDU structure given in @p result. This
385 * function returns @c 0 on error or a number greater than zero on
388 * @param data The raw data to parse as CoAP PDU
389 * @param length The actual size of @p data
390 * @param result The PDU structure to fill. Note that the structure must
391 * provide space for at least @p length bytes to hold the
393 * @param transport The transport type.
394 * @return A value greater than zero on success or @c 0 on error.
396 int coap_pdu_parse(unsigned char *data, size_t length, coap_pdu_t *pdu,
397 coap_transport_type transport);
401 * Get total message length from header.
403 * @param data The raw data to parse as CoAP PDU.
404 * @param size payload size of pdu.
405 * @return Total message length.
407 size_t coap_get_total_message_length(const unsigned char *data, size_t size);
410 * Get transport type of coap header for coap over tcp through payload size.
412 * @param size payload size of pdu.
413 * @return The transport type.
415 coap_transport_type coap_get_tcp_header_type_from_size(unsigned int size);
418 * Get transport type of coap header for coap over tcp through init-byte.
420 * @param legnth length value of init byte.
421 * @return The transport type.
423 coap_transport_type coap_get_tcp_header_type_from_initbyte(unsigned int length);
426 * Add length value in field of coap header for coap over tcp.
428 * @param pdu The pdu pointer.
429 * @param transport The transport type.
430 * @param length length value of init byte.
432 void coap_add_length(const coap_pdu_t *pdu, coap_transport_type transport,
433 unsigned int length);
436 * Get the value of length field of coap header for coap over tcp.
438 * @param pdu The pdu pointer.
439 * @param transport The transport type.
440 * @return length value of init byte.
442 unsigned int coap_get_length(const coap_pdu_t *pdu, coap_transport_type transport);
445 * Get pdu length from header of coap over tcp.
447 * @param header The header to parse.
448 * @return transport The transport type.
450 unsigned int coap_get_length_from_header(const unsigned char *header, coap_transport_type transport);
453 * Get length of header for coap over tcp.
455 * @param data The raw data to parse as CoAP PDU
456 * @return header length + token length
458 unsigned int coap_get_tcp_header_length(unsigned char *data);
461 * Get length of header without token length for coap over tcp.
463 * @param transport The transport type.
464 * @return header length.
466 unsigned int coap_get_tcp_header_length_for_transport(coap_transport_type transport);
471 * @param key delta of option
472 * @param length length of option
473 * @return total option length
475 size_t coap_get_opt_header_length(unsigned short key, size_t length);
479 * Add code in coap header.
481 * @param pdu The pdu pointer.
482 * @param transport The transport type.
483 * @param code The message code.
485 void coap_add_code(const coap_pdu_t *pdu, coap_transport_type transport,
489 * Get message code from coap header
491 * @param pdu The pdu pointer.
492 * @param transport The transport type.
493 * @return The message code.
495 unsigned int coap_get_code(const coap_pdu_t *pdu, coap_transport_type transport);
497 * Adds token of length @p len to @p pdu. Adding the token destroys
498 * any following contents of the pdu. Hence options and data must be
499 * added after coap_add_token() has been called. In @p pdu, length is
500 * set to @p len + @c 4, and max_delta is set to @c 0. This funtion
501 * returns @c 0 on error or a value greater than zero on success.
503 * @param pdu The pdu pointer.
504 * @param len The length of the new token.
505 * @param data The token to add.
506 * @param transport The transport type.
507 * @return A value greater than zero on success, or @c 0 on error.
509 int coap_add_token(coap_pdu_t *pdu, size_t len, const unsigned char *data,
510 coap_transport_type transport);
513 * Get token from coap header base on transport type
515 * @param pdu_hdr The header pointer of PDU.
516 * @param transport The transport type.
517 * @param token out parameter to get token.
518 * @param token_length out parameter to get token length.
520 void coap_get_token(const coap_hdr_t *pdu_hdr, coap_transport_type transport,
521 unsigned char **token, unsigned int *token_length);
524 * Adds option of given type to pdu that is passed as first
525 * parameter. coap_add_option() destroys the PDU's data, so
526 * coap_add_data() must be called after all options have been added.
527 * As coap_add_token() destroys the options following the token,
528 * the token must be added before coap_add_option() is called.
529 * This function returns the number of bytes written or @c 0 on error.
531 size_t coap_add_option(coap_pdu_t *pdu, unsigned short type, unsigned int len,
532 const unsigned char *data, coap_transport_type transport);
535 * Adds option of given type to pdu that is passed as first
536 * parameter, but does not write a val13ue. It works like coap_add_option with
537 * respect to calling sequence (i.e. after token and before data).
538 * This function returns a memory address to which the option data has to be
539 * written before the PDU can be sent, or @c NULL on error.
541 unsigned char *coap_add_option_later(coap_pdu_t *pdu, unsigned short type, unsigned int len);
544 * Adds given data to the pdu that is passed as first parameter. Note
545 * that the PDU's data is destroyed by coap_add_option(). coap_add_data()
546 * must be called only once per PDU, otherwise the result is undefined.
548 int coap_add_data(coap_pdu_t *pdu, unsigned int len, const unsigned char *data);
551 * Retrieves the length and data pointer of specified PDU. Returns 0 on error
552 * or 1 if *len and *data have correct values. Note that these values are
553 * destroyed with the pdu.
555 int coap_get_data(const coap_pdu_t *pdu, size_t *len, unsigned char **data);