libcoap  4.3.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  * Copyright (C) 2021-2022 Jon Shallow <supjps-libcoap@jpshallow.com>
6  *
7  * SPDX-License-Identifier: BSD-2-Clause
8  *
9  * This file is part of the CoAP library libcoap. Please see README for terms
10  * of use.
11  */
12 
18 #ifndef COAP_PDU_H_
19 #define COAP_PDU_H_
20 
21 #include "uri.h"
22 #include "coap_option.h"
23 
24 #ifdef WITH_LWIP
25 #include <lwip/pbuf.h>
26 #endif
27 
28 #include <stdint.h>
29 
37 #define COAP_DEFAULT_PORT 5683 /* CoAP default UDP/TCP port */
38 #define COAPS_DEFAULT_PORT 5684 /* CoAP default UDP/TCP port for secure transmission */
39 #define COAP_DEFAULT_MAX_AGE 60 /* default maximum object lifetime in seconds */
40 #ifndef COAP_DEFAULT_MTU
41 #define COAP_DEFAULT_MTU 1152
42 #endif /* COAP_DEFAULT_MTU */
43 
44 #define COAP_BERT_BASE 1152
45 
46 #ifndef COAP_DEFAULT_HOP_LIMIT
47 #define COAP_DEFAULT_HOP_LIMIT 16
48 #endif /* COAP_DEFAULT_HOP_LIMIT */
49 
50 #define COAP_DEFAULT_SCHEME "coap" /* the default scheme for CoAP URIs */
51 
53 #define COAP_DEFAULT_URI_WELLKNOWN ".well-known/core"
54 
55 /* CoAP message types */
56 
60 typedef enum coap_pdu_type_t {
61  COAP_MESSAGE_CON, /* 0 confirmable message (requires ACK/RST) */
62  COAP_MESSAGE_NON, /* 1 non-confirmable message (one-shot message) */
63  COAP_MESSAGE_ACK, /* 2 used to acknowledge confirmable messages */
64  COAP_MESSAGE_RST /* 3 indicates error in received messages */
66 
70 typedef enum coap_request_t {
75  COAP_REQUEST_FETCH, /* 5 RFC 8132 */
76  COAP_REQUEST_PATCH, /* 6 RFC 8132 */
77  COAP_REQUEST_IPATCH, /* 7 RFC 8132 */
79 
80 /*
81  * CoAP option numbers (be sure to update coap_option_check_critical() and
82  * coap_add_option() when adding options
83  */
84 
85 /*
86  * The C, U, and N flags indicate the properties
87  * Critical, Unsafe, and NoCacheKey, respectively.
88  * If U is set, then N has no meaning as per
89  * https://tools.ietf.org/html/rfc7252#section-5.10
90  * and is set to a -.
91  *
92  * Separately, R is for the options that can be repeated
93  *
94  * The least significant byte of the option is set as followed
95  * as per https://tools.ietf.org/html/rfc7252#section-5.4.6
96  *
97  * 0 1 2 3 4 5 6 7
98  * --+---+---+---+---+---+---+---+
99  * | NoCacheKey| U | C |
100  * --+---+---+---+---+---+---+---+
101  *
102  * https://tools.ietf.org/html/rfc8613#section-4 goes on to define E, I and U
103  * properties Encrypted and Integrity Protected, Integrity Protected Only, and
104  * Unprotected respectively. Integrity Protected Only is not currently used.
105  *
106  * An Option is tagged with CUNREIU with any of the letters replaced with _ if
107  * not set, or - for N if U is set (see above) for aiding understanding of the
108  * Option.
109  */
110 
111 #define COAP_OPTION_IF_MATCH 1 /* C__RE__, opaque, 0-8 B, RFC7252 */
112 #define COAP_OPTION_URI_HOST 3 /* CU-___U, String, 1-255 B, RFC7252 */
113 #define COAP_OPTION_ETAG 4 /* ___RE__, opaque, 1-8 B, RFC7252 */
114 #define COAP_OPTION_IF_NONE_MATCH 5 /* C___E__, empty, 0 B, RFC7252 */
115 #define COAP_OPTION_OBSERVE 6 /* _U-_E_U, empty/uint,0/0-3 B, RFC7641 */
116 #define COAP_OPTION_URI_PORT 7 /* CU-___U, uint, 0-2 B, RFC7252 */
117 #define COAP_OPTION_LOCATION_PATH 8 /* ___RE__, String, 0-255 B, RFC7252 */
118 #define COAP_OPTION_OSCORE 9 /* C_____U, *, 0-255 B, RFC8613 */
119 #define COAP_OPTION_URI_PATH 11 /* CU-RE__, String, 0-255 B, RFC7252 */
120 #define COAP_OPTION_CONTENT_FORMAT 12 /* ____E__, uint, 0-2 B, RFC7252 */
121 #define COAP_OPTION_CONTENT_TYPE COAP_OPTION_CONTENT_FORMAT
122 /* COAP_OPTION_MAXAGE default 60 seconds if not set */
123 #define COAP_OPTION_MAXAGE 14 /* _U-_E_U, uint, 0-4 B, RFC7252 */
124 #define COAP_OPTION_URI_QUERY 15 /* CU-RE__, String, 1-255 B, RFC7252 */
125 #define COAP_OPTION_HOP_LIMIT 16 /* ______U, uint, 1 B, RFC8768 */
126 #define COAP_OPTION_ACCEPT 17 /* C___E__, uint, 0-2 B, RFC7252 */
127 #define COAP_OPTION_LOCATION_QUERY 20 /* ___RE__, String, 0-255 B, RFC7252 */
128 #define COAP_OPTION_BLOCK2 23 /* CU-_E_U, uint, 0-3 B, RFC7959 */
129 #define COAP_OPTION_BLOCK1 27 /* CU-_E_U, uint, 0-3 B, RFC7959 */
130 #define COAP_OPTION_SIZE2 28 /* __N_E_U, uint, 0-4 B, RFC7959 */
131 #define COAP_OPTION_PROXY_URI 35 /* CU-___U, String, 1-1034 B, RFC7252 */
132 #define COAP_OPTION_PROXY_SCHEME 39 /* CU-___U, String, 1-255 B, RFC7252 */
133 #define COAP_OPTION_SIZE1 60 /* __N_E_U, uint, 0-4 B, RFC7252 */
134 #define COAP_OPTION_ECHO 252 /* _N__E_U, opaque, 0-40 B, RFC9175 */
135 #define COAP_OPTION_NORESPONSE 258 /* _U-_E_U, uint, 0-1 B, RFC7967 */
136 #define COAP_OPTION_RTAG 292 /* ___RE_U, opaque, 0-8 B, RFC9175 */
137 
138 #define COAP_MAX_OPT 65535
140 /* CoAP result codes (HTTP-Code / 100 * 40 + HTTP-Code % 100) */
141 
142 /* As of draft-ietf-core-coap-04, response codes are encoded to base
143  * 32, i.e. the three upper bits determine the response class while
144  * the remaining five fine-grained information specific to that class.
145  */
146 #define COAP_RESPONSE_CODE(N) (((N)/100 << 5) | (N)%100)
147 
148 /* Determines the class of response code C */
149 #define COAP_RESPONSE_CLASS(C) (((C) >> 5) & 0xFF)
150 
151 #ifndef SHORT_ERROR_RESPONSE
162 const char *coap_response_phrase(unsigned char code);
163 
164 #define COAP_ERROR_PHRASE_LENGTH 32
166 #else
167 #define coap_response_phrase(x) ((char *)NULL)
168 
169 #define COAP_ERROR_PHRASE_LENGTH 0
170 #endif /* SHORT_ERROR_RESPONSE */
171 
172 #define COAP_SIGNALING_CODE(N) (((N)/100 << 5) | (N)%100)
173 
181 
182 /* Applies to COAP_SIGNALING_CSM */
183 #define COAP_SIGNALING_OPTION_MAX_MESSAGE_SIZE 2
184 #define COAP_SIGNALING_OPTION_BLOCK_WISE_TRANSFER 4
185 /* Applies to COAP_SIGNALING_PING / COAP_SIGNALING_PONG */
186 #define COAP_SIGNALING_OPTION_CUSTODY 2
187 /* Applies to COAP_SIGNALING_RELEASE */
188 #define COAP_SIGNALING_OPTION_ALTERNATIVE_ADDRESS 2
189 #define COAP_SIGNALING_OPTION_HOLD_OFF 4
190 /* Applies to COAP_SIGNALING_ABORT */
191 #define COAP_SIGNALING_OPTION_BAD_CSM_OPTION 2
192 
193 /* CoAP media type encoding */
194 
195 #define COAP_MEDIATYPE_TEXT_PLAIN 0 /* text/plain (UTF-8) */
196 #define COAP_MEDIATYPE_APPLICATION_LINK_FORMAT 40 /* application/link-format */
197 #define COAP_MEDIATYPE_APPLICATION_XML 41 /* application/xml */
198 #define COAP_MEDIATYPE_APPLICATION_OCTET_STREAM 42 /* application/octet-stream */
199 #define COAP_MEDIATYPE_APPLICATION_RDF_XML 43 /* application/rdf+xml */
200 #define COAP_MEDIATYPE_APPLICATION_EXI 47 /* application/exi */
201 #define COAP_MEDIATYPE_APPLICATION_JSON 50 /* application/json */
202 #define COAP_MEDIATYPE_APPLICATION_CBOR 60 /* application/cbor */
203 #define COAP_MEDIATYPE_APPLICATION_CWT 61 /* application/cwt, RFC 8392 */
204 
205 /* Content formats from RFC 7390 */
206 #define COAP_MEDIATYPE_APPLICATION_COAP_GROUP_JSON 256 /* application/coap-group+json */
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 /* Content formats from RFC 8782 */
230 #define COAP_MEDIATYPE_APPLICATION_DOTS_CBOR 271 /* application/dots+cbor */
231 
232 /* Content formats from RFC 9200 */
233 #define COAP_MEDIATYPE_APPLICATION_ACE_CBOR 19 /* application/ace+cbor */
234 
235 /* Note that identifiers for registered media types are in the range 0-65535. We
236  * use an unallocated type here and hope for the best. */
237 #define COAP_MEDIATYPE_ANY 0xff /* any media type */
238 
243 typedef int coap_mid_t;
244 
246 #define COAP_INVALID_MID -1
247 
252 #define COAP_INVALID_TID COAP_INVALID_MID
253 
261 COAP_DEPRECATED typedef struct {
262  uint16_t key; /* the option key (no delta coding) */
263  unsigned int length;
264 } coap_option;
265 
266 #define COAP_OPTION_KEY(option) (option).key
267 #define COAP_OPTION_LENGTH(option) (option).length
268 #define COAP_OPTION_DATA(option) ((unsigned char *)&(option) + sizeof(coap_option))
269 
270 #ifdef WITH_LWIP
286 coap_pdu_t * coap_pdu_from_pbuf(struct pbuf *pbuf);
287 #endif
288 
292 typedef enum coap_proto_t {
299 
303 typedef enum coap_pdu_code_t {
305 
313 
341 
348 
364  coap_mid_t mid, size_t size);
365 
377  coap_session_t *session);
378 
387 void coap_delete_pdu(coap_pdu_t *pdu);
388 
402 coap_pdu_t *
403 coap_pdu_duplicate(const coap_pdu_t *old_pdu,
404  coap_session_t *session,
405  size_t token_length,
406  const uint8_t *token,
407  coap_opt_filter_t *drop_options);
408 
423 int coap_pdu_parse(coap_proto_t proto,
424  const uint8_t *data,
425  size_t length,
426  coap_pdu_t *pdu);
427 
442 int coap_add_token(coap_pdu_t *pdu,
443  size_t len,
444  const uint8_t *data);
445 
467 size_t coap_add_option(coap_pdu_t *pdu,
468  coap_option_num_t number,
469  size_t len,
470  const uint8_t *data);
471 
483 int coap_add_data(coap_pdu_t *pdu,
484  size_t len,
485  const uint8_t *data);
486 
499 uint8_t *coap_add_data_after(coap_pdu_t *pdu, size_t len);
500 
513 int coap_get_data(const coap_pdu_t *pdu,
514  size_t *len,
515  const uint8_t **data);
516 
534 int coap_get_data_large(const coap_pdu_t *pdu,
535  size_t *len,
536  const uint8_t **data,
537  size_t *offset,
538  size_t *total);
539 
548 
556 
565 
573 
582 
591 
599 void coap_pdu_set_mid(coap_pdu_t *pdu, coap_mid_t mid);
600 
603 #endif /* COAP_PDU_H_ */
Helpers for handling options in CoAP PDUs.
uint16_t coap_option_num_t
Definition: coap_option.h:20
coap_pdu_t * coap_pdu_duplicate(const coap_pdu_t *old_pdu, coap_session_t *session, size_t token_length, const uint8_t *token, coap_opt_filter_t *drop_options)
Duplicate an existing PDU.
Definition: pdu.c:167
coap_pdu_code_t coap_pdu_get_code(const coap_pdu_t *pdu)
Gets the PDU code associated with pdu.
Definition: pdu.c:1267
void coap_delete_pdu(coap_pdu_t *pdu)
Dispose of an CoAP PDU and frees associated storage.
Definition: pdu.c:154
void coap_pdu_set_code(coap_pdu_t *pdu, coap_pdu_code_t code)
Sets the PDU code in the pdu.
Definition: pdu.c:1272
int coap_mid_t
coap_mid_t is used to store the CoAP Message ID of a CoAP PDU.
Definition: pdu.h:243
coap_request_t
CoAP PDU Request methods.
Definition: pdu.h:70
#define COAP_RESPONSE_CODE(N)
Definition: pdu.h:146
#define COAP_SIGNALING_CODE(N)
Definition: pdu.h:172
coap_proto_t
CoAP protocol types.
Definition: pdu.h:292
coap_pdu_code_t
Set of codes available for a PDU.
Definition: pdu.h:303
coap_pdu_t * coap_new_pdu(coap_pdu_type_t type, coap_pdu_code_t code, coap_session_t *session)
Creates a new CoAP PDU.
Definition: pdu.c:144
coap_pdu_type_t
CoAP PDU message type definitions.
Definition: pdu.h:60
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:275
void coap_pdu_set_type(coap_pdu_t *pdu, coap_pdu_type_t type)
Sets the PDU type in the pdu.
Definition: pdu.c:1281
size_t coap_add_option(coap_pdu_t *pdu, coap_option_num_t number, size_t len, const uint8_t *data)
Adds option of given number to pdu that is passed as first parameter.
Definition: pdu.c:605
coap_pdu_signaling_proto_t
Definition: pdu.h:174
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.
Definition: pdu.c:694
coap_pdu_type_t coap_pdu_get_type(const coap_pdu_t *pdu)
Gets the PDU type associated with pdu.
Definition: pdu.c:1277
int coap_get_data(const coap_pdu_t *pdu, size_t *len, const uint8_t **data)
Retrieves the length and data pointer of specified PDU.
Definition: pdu.c:713
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:1163
void coap_pdu_set_mid(coap_pdu_t *pdu, coap_mid_t mid)
Sets the message id in the pdu.
Definition: pdu.c:1298
int coap_get_data_large(const coap_pdu_t *pdu, size_t *len, const uint8_t **data, size_t *offset, size_t *total)
Retrieves the data from a PDU, with support for large bodies of data that spans multiple PDUs.
Definition: pdu.c:721
const char * coap_response_phrase(unsigned char code)
Returns a human-readable response phrase for the specified CoAP response code.
Definition: pdu.c:788
coap_mid_t coap_pdu_get_mid(const coap_pdu_t *pdu)
Gets the message id associated with pdu.
Definition: pdu.c:1294
coap_pdu_t * coap_pdu_init(coap_pdu_type_t type, coap_pdu_code_t code, coap_mid_t mid, size_t size)
Creates a new CoAP PDU with at least enough storage space for the given size maximum message size.
Definition: pdu.c:99
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:682
coap_bin_const_t coap_pdu_get_token(const coap_pdu_t *pdu)
Gets the token associated with pdu.
Definition: pdu.c:1286
@ COAP_REQUEST_PUT
Definition: pdu.h:73
@ COAP_REQUEST_DELETE
Definition: pdu.h:74
@ COAP_REQUEST_GET
Definition: pdu.h:71
@ COAP_REQUEST_FETCH
Definition: pdu.h:75
@ COAP_REQUEST_PATCH
Definition: pdu.h:76
@ COAP_REQUEST_IPATCH
Definition: pdu.h:77
@ COAP_REQUEST_POST
Definition: pdu.h:72
@ COAP_PROTO_DTLS
Definition: pdu.h:295
@ COAP_PROTO_UDP
Definition: pdu.h:294
@ COAP_PROTO_NONE
Definition: pdu.h:293
@ COAP_PROTO_TLS
Definition: pdu.h:297
@ COAP_PROTO_TCP
Definition: pdu.h:296
@ COAP_RESPONSE_CODE_INTERNAL_ERROR
Definition: pdu.h:334
@ COAP_RESPONSE_CODE_HOP_LIMIT_REACHED
Definition: pdu.h:340
@ COAP_SIGNALING_CODE_ABORT
Definition: pdu.h:346
@ COAP_RESPONSE_CODE_PRECONDITION_FAILED
Definition: pdu.h:329
@ COAP_RESPONSE_CODE_NOT_ALLOWED
Definition: pdu.h:325
@ COAP_RESPONSE_CODE_CHANGED
Definition: pdu.h:317
@ COAP_REQUEST_CODE_PUT
Definition: pdu.h:308
@ COAP_REQUEST_CODE_POST
Definition: pdu.h:307
@ COAP_RESPONSE_CODE_NOT_ACCEPTABLE
Definition: pdu.h:326
@ COAP_SIGNALING_CODE_CSM
Definition: pdu.h:342
@ COAP_REQUEST_CODE_PATCH
Definition: pdu.h:311
@ COAP_RESPONSE_CODE_PROXYING_NOT_SUPPORTED
Definition: pdu.h:339
@ COAP_RESPONSE_CODE_BAD_REQUEST
Definition: pdu.h:320
@ COAP_SIGNALING_CODE_PING
Definition: pdu.h:343
@ COAP_RESPONSE_CODE_INCOMPLETE
Definition: pdu.h:327
@ COAP_REQUEST_CODE_DELETE
Definition: pdu.h:309
@ COAP_SIGNALING_CODE_PONG
Definition: pdu.h:344
@ COAP_RESPONSE_CODE_NOT_IMPLEMENTED
Definition: pdu.h:335
@ COAP_RESPONSE_CODE_NOT_FOUND
Definition: pdu.h:324
@ COAP_RESPONSE_CODE_BAD_GATEWAY
Definition: pdu.h:336
@ COAP_RESPONSE_CODE_BAD_OPTION
Definition: pdu.h:322
@ COAP_RESPONSE_CODE_REQUEST_TOO_LARGE
Definition: pdu.h:330
@ COAP_RESPONSE_CODE_TOO_MANY_REQUESTS
Definition: pdu.h:333
@ COAP_RESPONSE_CODE_CONFLICT
Definition: pdu.h:328
@ COAP_RESPONSE_CODE_DELETED
Definition: pdu.h:315
@ COAP_RESPONSE_CODE_UNAUTHORIZED
Definition: pdu.h:321
@ COAP_RESPONSE_CODE_CREATED
Definition: pdu.h:314
@ COAP_EMPTY_CODE
Definition: pdu.h:304
@ COAP_RESPONSE_CODE_CONTENT
Definition: pdu.h:318
@ COAP_RESPONSE_CODE_UNPROCESSABLE
Definition: pdu.h:332
@ COAP_RESPONSE_CODE_CONTINUE
Definition: pdu.h:319
@ COAP_RESPONSE_CODE_VALID
Definition: pdu.h:316
@ COAP_RESPONSE_CODE_UNSUPPORTED_CONTENT_FORMAT
Definition: pdu.h:331
@ COAP_REQUEST_CODE_GET
Definition: pdu.h:306
@ COAP_SIGNALING_CODE_RELEASE
Definition: pdu.h:345
@ COAP_REQUEST_CODE_FETCH
Definition: pdu.h:310
@ COAP_RESPONSE_CODE_GATEWAY_TIMEOUT
Definition: pdu.h:338
@ COAP_REQUEST_CODE_IPATCH
Definition: pdu.h:312
@ COAP_RESPONSE_CODE_SERVICE_UNAVAILABLE
Definition: pdu.h:337
@ COAP_RESPONSE_CODE_FORBIDDEN
Definition: pdu.h:323
@ COAP_MESSAGE_NON
Definition: pdu.h:62
@ COAP_MESSAGE_ACK
Definition: pdu.h:63
@ COAP_MESSAGE_CON
Definition: pdu.h:61
@ COAP_MESSAGE_RST
Definition: pdu.h:64
@ COAP_SIGNALING_RELEASE
Definition: pdu.h:178
@ COAP_SIGNALING_CSM
Definition: pdu.h:175
@ COAP_SIGNALING_PONG
Definition: pdu.h:177
@ COAP_SIGNALING_PING
Definition: pdu.h:176
@ COAP_SIGNALING_ABORT
Definition: pdu.h:179
#define COAP_DEPRECATED
Definition: libcoap.h:53
CoAP binary data definition with const data.
Definition: str.h:64
unsigned int length
Definition: pdu.h:263
uint16_t key
Definition: pdu.h:262
structure for CoAP PDUs
Abstraction of virtual session that can be attached to coap_context_t (client) or coap_endpoint_t (se...
Helper functions for URI treatment.