libcoap  4.2.1
pdu.h
Go to the documentation of this file.
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 
15 #ifndef COAP_PDU_H_
16 #define COAP_PDU_H_
17 
18 #include "uri.h"
19 
20 struct coap_session_t;
21 
22 #ifdef WITH_LWIP
23 #include <lwip/pbuf.h>
24 #endif
25 
26 #include <stdint.h>
27 
28 #define COAP_DEFAULT_PORT 5683 /* CoAP default UDP/TCP port */
29 #define COAPS_DEFAULT_PORT 5684 /* CoAP default UDP/TCP port for secure transmission */
30 #define COAP_DEFAULT_MAX_AGE 60 /* default maximum object lifetime in seconds */
31 #ifndef COAP_DEFAULT_MTU
32 #define COAP_DEFAULT_MTU 1152
33 #endif /* COAP_DEFAULT_MTU */
34 
35 /* TCP Message format constants, do not modify */
36 #define COAP_MESSAGE_SIZE_OFFSET_TCP8 13
37 #define COAP_MESSAGE_SIZE_OFFSET_TCP16 269 /* 13 + 256 */
38 #define COAP_MESSAGE_SIZE_OFFSET_TCP32 65805 /* 269 + 65536 */
39 
40 /* Derived message size limits */
41 #define COAP_MAX_MESSAGE_SIZE_TCP0 (COAP_MESSAGE_SIZE_OFFSET_TCP8-1) /* 12 */
42 #define COAP_MAX_MESSAGE_SIZE_TCP8 (COAP_MESSAGE_SIZE_OFFSET_TCP16-1) /* 268 */
43 #define COAP_MAX_MESSAGE_SIZE_TCP16 (COAP_MESSAGE_SIZE_OFFSET_TCP32-1) /* 65804 */
44 #define COAP_MAX_MESSAGE_SIZE_TCP32 (COAP_MESSAGE_SIZE_OFFSET_TCP32+0xFFFFFFFF)
45 
46 #ifndef COAP_DEFAULT_MAX_PDU_RX_SIZE
47 #if defined(WITH_CONTIKI) || defined(WITH_LWIP)
48 #define COAP_DEFAULT_MAX_PDU_RX_SIZE (COAP_MAX_MESSAGE_SIZE_TCP16+4)
49 #else
50 /* 8 MiB max-message-size plus some space for options */
51 #define COAP_DEFAULT_MAX_PDU_RX_SIZE (8*1024*1024+256)
52 #endif
53 #endif /* COAP_DEFAULT_MAX_PDU_RX_SIZE */
54 
55 #ifndef COAP_DEBUG_BUF_SIZE
56 #if defined(WITH_CONTIKI) || defined(WITH_LWIP)
57 #define COAP_DEBUG_BUF_SIZE 128
58 #else /* defined(WITH_CONTIKI) || defined(WITH_LWIP) */
59 /* 1024 derived from RFC7252 4.6. Message Size max payload */
60 #define COAP_DEBUG_BUF_SIZE (8 + 1024 * 2)
61 #endif /* defined(WITH_CONTIKI) || defined(WITH_LWIP) */
62 #endif /* COAP_DEBUG_BUF_SIZE */
63 
64 #define COAP_DEFAULT_VERSION 1 /* version of CoAP supported */
65 #define COAP_DEFAULT_SCHEME "coap" /* the default scheme for CoAP URIs */
66 
68 #define COAP_DEFAULT_URI_WELLKNOWN ".well-known/core"
69 
70 /* CoAP message types */
71 
72 #define COAP_MESSAGE_CON 0 /* confirmable message (requires ACK/RST) */
73 #define COAP_MESSAGE_NON 1 /* non-confirmable message (one-shot message) */
74 #define COAP_MESSAGE_ACK 2 /* used to acknowledge confirmable messages */
75 #define COAP_MESSAGE_RST 3 /* indicates error in received messages */
76 
77 /* CoAP request methods */
78 
79 #define COAP_REQUEST_GET 1
80 #define COAP_REQUEST_POST 2
81 #define COAP_REQUEST_PUT 3
82 #define COAP_REQUEST_DELETE 4
83 #define COAP_REQUEST_FETCH 5 /* RFC 8132 */
84 #define COAP_REQUEST_PATCH 6 /* RFC 8132 */
85 #define COAP_REQUEST_IPATCH 7 /* RFC 8132 */
86 
87 /*
88  * CoAP option types (be sure to update coap_option_check_critical() when
89  * adding options
90  */
91 
92 #define COAP_OPTION_IF_MATCH 1 /* C, opaque, 0-8 B, (none) */
93 #define COAP_OPTION_URI_HOST 3 /* C, String, 1-255 B, destination address */
94 #define COAP_OPTION_ETAG 4 /* E, opaque, 1-8 B, (none) */
95 #define COAP_OPTION_IF_NONE_MATCH 5 /* empty, 0 B, (none) */
96 #define COAP_OPTION_URI_PORT 7 /* C, uint, 0-2 B, destination port */
97 #define COAP_OPTION_LOCATION_PATH 8 /* E, String, 0-255 B, - */
98 #define COAP_OPTION_URI_PATH 11 /* C, String, 0-255 B, (none) */
99 #define COAP_OPTION_CONTENT_FORMAT 12 /* E, uint, 0-2 B, (none) */
100 #define COAP_OPTION_CONTENT_TYPE COAP_OPTION_CONTENT_FORMAT
101 #define COAP_OPTION_MAXAGE 14 /* E, uint, 0--4 B, 60 Seconds */
102 #define COAP_OPTION_URI_QUERY 15 /* C, String, 1-255 B, (none) */
103 #define COAP_OPTION_ACCEPT 17 /* C, uint, 0-2 B, (none) */
104 #define COAP_OPTION_LOCATION_QUERY 20 /* E, String, 0-255 B, (none) */
105 #define COAP_OPTION_SIZE2 28 /* E, uint, 0-4 B, (none) */
106 #define COAP_OPTION_PROXY_URI 35 /* C, String, 1-1034 B, (none) */
107 #define COAP_OPTION_PROXY_SCHEME 39 /* C, String, 1-255 B, (none) */
108 #define COAP_OPTION_SIZE1 60 /* E, uint, 0-4 B, (none) */
109 
110 /* option types from RFC 7641 */
111 
112 #define COAP_OPTION_OBSERVE 6 /* E, empty/uint, 0 B/0-3 B, (none) */
113 #define COAP_OPTION_SUBSCRIPTION COAP_OPTION_OBSERVE
114 
115 /* selected option types from RFC 7959 */
116 
117 #define COAP_OPTION_BLOCK2 23 /* C, uint, 0--3 B, (none) */
118 #define COAP_OPTION_BLOCK1 27 /* C, uint, 0--3 B, (none) */
119 
120 /* selected option types from RFC 7967 */
121 
122 #define COAP_OPTION_NORESPONSE 258 /* N, uint, 0--1 B, 0 */
123 
124 #define COAP_MAX_OPT 65535
126 /* CoAP result codes (HTTP-Code / 100 * 40 + HTTP-Code % 100) */
127 
128 /* As of draft-ietf-core-coap-04, response codes are encoded to base
129  * 32, i.e. the three upper bits determine the response class while
130  * the remaining five fine-grained information specific to that class.
131  */
132 #define COAP_RESPONSE_CODE(N) (((N)/100 << 5) | (N)%100)
133 
134 /* Determines the class of response code C */
135 #define COAP_RESPONSE_CLASS(C) (((C) >> 5) & 0xFF)
136 
137 #ifndef SHORT_ERROR_RESPONSE
138 
148 const char *coap_response_phrase(unsigned char code);
149 
150 #define COAP_ERROR_PHRASE_LENGTH 32
152 #else
153 #define coap_response_phrase(x) ((char *)NULL)
154 
155 #define COAP_ERROR_PHRASE_LENGTH 0
156 #endif /* SHORT_ERROR_RESPONSE */
157 
158 /* The following definitions exist for backwards compatibility */
159 #if 0 /* this does not exist any more */
160 #define COAP_RESPONSE_100 40 /* 100 Continue */
161 #endif
162 #define COAP_RESPONSE_200 COAP_RESPONSE_CODE(200) /* 2.00 OK */
163 #define COAP_RESPONSE_201 COAP_RESPONSE_CODE(201) /* 2.01 Created */
164 #define COAP_RESPONSE_304 COAP_RESPONSE_CODE(203) /* 2.03 Valid */
165 #define COAP_RESPONSE_400 COAP_RESPONSE_CODE(400) /* 4.00 Bad Request */
166 #define COAP_RESPONSE_404 COAP_RESPONSE_CODE(404) /* 4.04 Not Found */
167 #define COAP_RESPONSE_405 COAP_RESPONSE_CODE(405) /* 4.05 Method Not Allowed */
168 #define COAP_RESPONSE_415 COAP_RESPONSE_CODE(415) /* 4.15 Unsupported Media Type */
169 #define COAP_RESPONSE_500 COAP_RESPONSE_CODE(500) /* 5.00 Internal Server Error */
170 #define COAP_RESPONSE_501 COAP_RESPONSE_CODE(501) /* 5.01 Not Implemented */
171 #define COAP_RESPONSE_503 COAP_RESPONSE_CODE(503) /* 5.03 Service Unavailable */
172 #define COAP_RESPONSE_504 COAP_RESPONSE_CODE(504) /* 5.04 Gateway Timeout */
173 #if 0 /* these response codes do not have a valid code any more */
174 # define COAP_RESPONSE_X_240 240 /* Token Option required by server */
175 # define COAP_RESPONSE_X_241 241 /* Uri-Authority Option required by server */
176 #endif
177 #define COAP_RESPONSE_X_242 COAP_RESPONSE_CODE(402) /* Critical Option not supported */
178 
179 #define COAP_SIGNALING_CODE(N) (((N)/100 << 5) | (N)%100)
180 #define COAP_SIGNALING_CSM COAP_SIGNALING_CODE(701)
181 #define COAP_SIGNALING_PING COAP_SIGNALING_CODE(702)
182 #define COAP_SIGNALING_PONG COAP_SIGNALING_CODE(703)
183 #define COAP_SIGNALING_RELEASE COAP_SIGNALING_CODE(704)
184 #define COAP_SIGNALING_ABORT COAP_SIGNALING_CODE(705)
185 
186 /* Applies to COAP_SIGNALING_CSM */
187 #define COAP_SIGNALING_OPTION_MAX_MESSAGE_SIZE 2
188 #define COAP_SIGNALING_OPTION_BLOCK_WISE_TRANSFER 4
189 /* Applies to COAP_SIGNALING_PING / COAP_SIGNALING_PONG */
190 #define COAP_SIGNALING_OPTION_CUSTODY 2
191 /* Applies to COAP_SIGNALING_RELEASE */
192 #define COAP_SIGNALING_OPTION_ALTERNATIVE_ADDRESS 2
193 #define COAP_SIGNALING_OPTION_HOLD_OFF 4
194 /* Applies to COAP_SIGNALING_ABORT */
195 #define COAP_SIGNALING_OPTION_BAD_CSM_OPTION 2
196 
197 /* CoAP media type encoding */
198 
199 #define COAP_MEDIATYPE_TEXT_PLAIN 0 /* text/plain (UTF-8) */
200 #define COAP_MEDIATYPE_APPLICATION_LINK_FORMAT 40 /* application/link-format */
201 #define COAP_MEDIATYPE_APPLICATION_XML 41 /* application/xml */
202 #define COAP_MEDIATYPE_APPLICATION_OCTET_STREAM 42 /* application/octet-stream */
203 #define COAP_MEDIATYPE_APPLICATION_RDF_XML 43 /* application/rdf+xml */
204 #define COAP_MEDIATYPE_APPLICATION_EXI 47 /* application/exi */
205 #define COAP_MEDIATYPE_APPLICATION_JSON 50 /* application/json */
206 #define COAP_MEDIATYPE_APPLICATION_CBOR 60 /* application/cbor */
207 
208 /* Content formats from RFC 8152 */
209 #define COAP_MEDIATYPE_APPLICATION_COSE_SIGN 98 /* application/cose; cose-type="cose-sign" */
210 #define COAP_MEDIATYPE_APPLICATION_COSE_SIGN1 18 /* application/cose; cose-type="cose-sign1" */
211 #define COAP_MEDIATYPE_APPLICATION_COSE_ENCRYPT 96 /* application/cose; cose-type="cose-encrypt" */
212 #define COAP_MEDIATYPE_APPLICATION_COSE_ENCRYPT0 16 /* application/cose; cose-type="cose-encrypt0" */
213 #define COAP_MEDIATYPE_APPLICATION_COSE_MAC 97 /* application/cose; cose-type="cose-mac" */
214 #define COAP_MEDIATYPE_APPLICATION_COSE_MAC0 17 /* application/cose; cose-type="cose-mac0" */
215 
216 #define COAP_MEDIATYPE_APPLICATION_COSE_KEY 101 /* application/cose-key */
217 #define COAP_MEDIATYPE_APPLICATION_COSE_KEY_SET 102 /* application/cose-key-set */
218 
219 /* Content formats from RFC 8428 */
220 #define COAP_MEDIATYPE_APPLICATION_SENML_JSON 110 /* application/senml+json */
221 #define COAP_MEDIATYPE_APPLICATION_SENSML_JSON 111 /* application/sensml+json */
222 #define COAP_MEDIATYPE_APPLICATION_SENML_CBOR 112 /* application/senml+cbor */
223 #define COAP_MEDIATYPE_APPLICATION_SENSML_CBOR 113 /* application/sensml+cbor */
224 #define COAP_MEDIATYPE_APPLICATION_SENML_EXI 114 /* application/senml-exi */
225 #define COAP_MEDIATYPE_APPLICATION_SENSML_EXI 115 /* application/sensml-exi */
226 #define COAP_MEDIATYPE_APPLICATION_SENML_XML 310 /* application/senml+xml */
227 #define COAP_MEDIATYPE_APPLICATION_SENSML_XML 311 /* application/sensml+xml */
228 
229 /* Note that identifiers for registered media types are in the range 0-65535. We
230  * use an unallocated type here and hope for the best. */
231 #define COAP_MEDIATYPE_ANY 0xff /* any media type */
232 
238 typedef int coap_tid_t;
239 
241 #define COAP_INVALID_TID -1
242 
247 #define COAP_DROPPED_RESPONSE -2
248 
249 #define COAP_PDU_DELAYED -3
250 
251 #define COAP_OPT_LONG 0x0F /* OC == 0b1111 indicates that the option list
252  * in a CoAP message is limited by 0b11110000
253  * marker */
254 
255 #define COAP_OPT_END 0xF0 /* end marker */
256 
257 #define COAP_PAYLOAD_START 0xFF /* payload marker */
258 
266 COAP_DEPRECATED typedef struct {
267  uint16_t key; /* the option key (no delta coding) */
268  unsigned int length;
269 } coap_option;
270 
271 #define COAP_OPTION_KEY(option) (option).key
272 #define COAP_OPTION_LENGTH(option) (option).length
273 #define COAP_OPTION_DATA(option) ((unsigned char *)&(option) + sizeof(coap_option))
274 
287 typedef struct coap_pdu_t {
293  uint16_t tid;
294  uint16_t max_delta;
295  size_t alloc_size;
296  size_t used_size;
297  size_t max_size;
300 #ifdef WITH_LWIP
301  struct pbuf *pbuf;
309 #endif
310 } coap_pdu_t;
311 
312 #define COAP_PDU_IS_EMPTY(pdu) ((pdu)->code == 0)
313 #define COAP_PDU_IS_REQUEST(pdu) (!COAP_PDU_IS_EMPTY(pdu) && (pdu)->code < 32)
314 #define COAP_PDU_IS_RESPONSE(pdu) ((pdu)->code >= 64 && (pdu)->code < 224)
315 #define COAP_PDU_IS_SIGNALING(pdu) ((pdu)->code >= 224)
316 
317 #define COAP_PDU_MAX_UDP_HEADER_SIZE 4
318 #define COAP_PDU_MAX_TCP_HEADER_SIZE 6
319 
320 #ifdef WITH_LWIP
321 
336 coap_pdu_t * coap_pdu_from_pbuf(struct pbuf *pbuf);
337 #endif
338 
343 #define COAP_PROTO_NONE 0
344 #define COAP_PROTO_UDP 1
345 #define COAP_PROTO_DTLS 2
346 #define COAP_PROTO_TCP 3
347 #define COAP_PROTO_TLS 4
348 
363 coap_pdu_t *
364 coap_pdu_init(uint8_t type, uint8_t code, uint16_t tid, size_t size);
365 
375 int coap_pdu_resize(coap_pdu_t *pdu, size_t new_size);
376 
383 void coap_pdu_clear(coap_pdu_t *pdu, size_t size);
384 
388 coap_pdu_t *coap_new_pdu(const struct coap_session_t *session);
389 
398 
409  const uint8_t *data);
410 
423  const uint8_t *data,
424  size_t length);
425 
434 
447 
463  const uint8_t *data,
464  size_t length,
465  coap_pdu_t *pdu);
479 int coap_add_token(coap_pdu_t *pdu,
480  size_t len,
481  const uint8_t *data);
482 
491 size_t coap_add_option(coap_pdu_t *pdu,
492  uint16_t type,
493  size_t len,
494  const uint8_t *data);
495 
504  uint16_t type,
505  size_t len);
506 
512 int coap_add_data(coap_pdu_t *pdu,
513  size_t len,
514  const uint8_t *data);
515 
523 uint8_t *coap_add_data_after(coap_pdu_t *pdu, size_t len);
524 
530 int coap_get_data(const coap_pdu_t *pdu,
531  size_t *len,
532  uint8_t **data);
533 
542 
543 #endif /* COAP_PDU_H_ */
uint8_t type
message type
Definition: pdu.h:288
uint8_t code
request method (value 1–10) or response code (value 40-255)
Definition: pdu.h:289
const char * coap_response_phrase(unsigned char code)
Returns a human-readable response phrase for the specified CoAP response code.
Definition: pdu.c:370
void coap_pdu_clear(coap_pdu_t *pdu, size_t size)
Clears any contents from pdu and resets used_size, and data pointers.
Definition: pdu.c:34
uint8_t coap_proto_t
Definition: pdu.h:339
size_t coap_pdu_parse_size(coap_proto_t proto, const uint8_t *data, size_t length)
Parses data to extract the message size.
Definition: pdu.c:428
int coap_add_token(coap_pdu_t *pdu, size_t len, const uint8_t *data)
Adds token of length len to pdu.
Definition: pdu.c:191
uint8_t * coap_add_option_later(coap_pdu_t *pdu, uint16_t type, size_t len)
Adds option of given type to pdu that is passed as first parameter, but does not write a value...
Definition: pdu.c:252
coap_pdu_t * coap_new_pdu(const struct coap_session_t *session)
Creates a new CoAP PDU.
Definition: pdu.c:119
int coap_tid_t
coap_tid_t is used to store CoAP transaction id, i.e.
Definition: pdu.h:238
unsigned int length
Definition: pdu.h:268
int coap_pdu_parse(coap_proto_t proto, const uint8_t *data, size_t length, coap_pdu_t *pdu)
Parses data into the CoAP PDU structure given in result.
Definition: pdu.c:543
int coap_add_data(coap_pdu_t *pdu, size_t len, const uint8_t *data)
Adds given data to the pdu that is passed as first parameter.
Definition: pdu.c:288
size_t coap_add_option(coap_pdu_t *pdu, uint16_t type, size_t len, const uint8_t *data)
Adds option of given type to pdu that is passed as first parameter.
Definition: pdu.c:215
int coap_get_data(const coap_pdu_t *pdu, size_t *len, uint8_t **data)
Retrieves the length and data pointer of specified PDU.
Definition: pdu.c:318
int coap_pdu_parse_header(coap_pdu_t *pdu, coap_proto_t proto)
Decode the protocol specific header for the specified PDU.
Definition: pdu.c:460
coap_pdu_t * coap_pdu_init(uint8_t type, uint8_t code, uint16_t tid, size_t size)
Creates a new CoAP PDU with at least enough storage space for the given size maximum message size...
Definition: pdu.c:79
int coap_pdu_resize(coap_pdu_t *pdu, size_t new_size)
Dynamically grows the size of pdu to new_size.
Definition: pdu.c:140
structure for CoAP PDUs token, if any, follows the fixed size header, then options until payload mark...
Definition: pdu.h:287
uint8_t * data
first byte of payload, if any
Definition: pdu.h:299
coap_proto_t proto
protocol used
Definition: coap_session.h:60
size_t used_size
used bytes of storage for token, options and payload
Definition: pdu.h:296
size_t alloc_size
allocated storage for token, options and payload
Definition: pdu.h:295
uint8_t * token
first byte of token, if any, or options
Definition: pdu.h:298
#define COAP_DEPRECATED
Definition: libcoap.h:46
size_t max_size
maximum size for token, options and payload, or zero for variable size pdu
Definition: pdu.h:297
coap_session_type_t type
client or server side socket
Definition: coap_session.h:61
struct coap_pdu_t coap_pdu_t
structure for CoAP PDUs token, if any, follows the fixed size header, then options until payload mark...
uint16_t key
Definition: pdu.h:267
uint16_t max_delta
highest option number
Definition: pdu.h:294
void coap_delete_pdu(coap_pdu_t *)
Dispose of an CoAP PDU and frees associated storage.
Definition: pdu.c:127
uint8_t max_hdr_size
space reserved for protocol-specific header
Definition: pdu.h:290
size_t coap_pdu_encode_header(coap_pdu_t *pdu, coap_proto_t proto)
Compose the protocol specific header for the specified PDU.
Definition: pdu.c:568
uint8_t * coap_add_data_after(coap_pdu_t *pdu, size_t len)
Adds given data to the pdu that is passed as first parameter but does not copyt it.
Definition: pdu.c:300
uint8_t hdr_size
actaul size used for protocol-specific header
Definition: pdu.h:291
unsigned char uint8_t
Definition: uthash.h:79
uint8_t token_length
length of Token
Definition: pdu.h:292
int coap_pdu_parse_opt(coap_pdu_t *pdu)
Verify consistency in the given CoAP PDU structure and locate the data.
Definition: pdu.c:492
size_t coap_pdu_parse_header_size(coap_proto_t proto, const uint8_t *data)
Interprets data to determine the number of bytes in the header.
Definition: pdu.c:405
uint16_t tid
transaction id, if any, in regular host byte order
Definition: pdu.h:293