coap_option.h
Go to the documentation of this file.
1 /**
2  * @file coap_option.h
3  * @brief CoAP option formatting and parsing
4  *
5  * @section License
6  *
7  * SPDX-License-Identifier: GPL-2.0-or-later
8  *
9  * Copyright (C) 2010-2019 Oryx Embedded SARL. All rights reserved.
10  *
11  * This file is part of CycloneTCP Open.
12  *
13  * This program is free software; you can redistribute it and/or
14  * modify it under the terms of the GNU General Public License
15  * as published by the Free Software Foundation; either version 2
16  * of the License, or (at your option) any later version.
17  *
18  * This program is distributed in the hope that it will be useful,
19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21  * GNU General Public License for more details.
22  *
23  * You should have received a copy of the GNU General Public License
24  * along with this program; if not, write to the Free Software Foundation,
25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
26  *
27  * @author Oryx Embedded SARL (www.oryx-embedded.com)
28  * @version 1.9.6
29  **/
30 
31 #ifndef _COAP_OPTION_H
32 #define _COAP_OPTION_H
33 
34 //Dependencies
35 #include "core/net.h"
36 #include "coap/coap_common.h"
37 #include "coap/coap_message.h"
38 
39 //Option delta encoding
40 #define COAP_OPT_DELTA_8_BITS 13
41 #define COAP_OPT_DELTA_16_BITS 14
42 #define COAP_OPT_DELTA_RESERVED 15
43 #define COAP_OPT_DELTA_MINUS_8_BITS 13
44 #define COAP_OPT_DELTA_MINUS_16_BITS 269
45 
46 //Option length encoding
47 #define COAP_OPT_LEN_8_BITS 13
48 #define COAP_OPT_LEN_16_BITS 14
49 #define COAP_OPT_LEN_RESERVED 15
50 #define COAP_OPT_LEN_MINUS_8_BITS 13
51 #define COAP_OPT_LEN_MINUS_16_BITS 269
52 
53 //Default Max-Age option value
54 #define COAP_DEFAULT_MAX_AGE 60
55 
56 //Test whether an option is critical
57 #define COAP_IS_OPTION_CRITICAL(num) (((num) & 0x01U) ? TRUE : FALSE)
58 //Test whether an option is unsafe to forward
59 #define COAP_IS_OPTION_UNSAFE(num) (((num) & 0x02U) ? TRUE : FALSE)
60 
61 //Set block number
62 #define COAP_SET_BLOCK_NUM(value, n) value = ((value) & 0x0FU) | ((n) << 4U)
63 //Set More flag
64 #define COAP_SET_BLOCK_M(value, m) value = ((value) & ~0x08U) | (((m) << 3U) & 0x08U)
65 //Set block size
66 #define COAP_SET_BLOCK_SZX(value, s) value = ((value) & ~0x07U) | ((s) & 0x07U)
67 
68 //Get block number
69 #define COAP_GET_BLOCK_NUM(value) ((value) >> 4U)
70 //Get More flag
71 #define COAP_GET_BLOCK_M(value) (((value) >> 3U) & 0x01U)
72 //Get block size
73 #define COAP_GET_BLOCK_SZX(value) ((value) & 0x07U)
74 
75 //Get block size (in bytes)
76 #define COAP_GET_BLOCK_SIZE(value) (16U << ((value) & 0x07U))
77 //Get block position from the beginning of the resource (in bytes)
78 #define COAP_GET_BLOCK_POS(value) (((value) & ~0x0FU) << ((value) & 0x07U))
79 
80 //C++ guard
81 #ifdef __cplusplus
82 extern "C" {
83 #endif
84 
85 
86 /**
87  * @brief CoAP options
88  **/
89 
90 typedef enum
91 {
92  COAP_OPT_IF_MATCH = 1, //RFC 7252
93  COAP_OPT_URI_HOST = 3, //RFC 7252
94  COAP_OPT_ETAG = 4, //RFC 7252
95  COAP_OPT_IF_NONE_MATCH = 5, //RFC 7252
96  COAP_OPT_OBSERVE = 6, //RFC 7641
97  COAP_OPT_URI_PORT = 7, //RFC 7252
98  COAP_OPT_LOCATION_PATH = 8, //RFC 7252
99  COAP_OPT_URI_PATH = 11, //RFC 7252
100  COAP_OPT_CONTENT_FORMAT = 12, //RFC 7252
101  COAP_OPT_MAX_AGE = 14, //RFC 7252
102  COAP_OPT_URI_QUERY = 15, //RFC 7252
103  COAP_OPT_ACCEPT = 17, //RFC 7252
104  COAP_OPT_LOCATION_QUERY = 20, //RFC 7252
105  COAP_OPT_BLOCK2 = 23, //RFC 7959
106  COAP_OPT_BLOCK1 = 27, //RFC 7959
107  COAP_OPT_SIZE2 = 28, //RFC 7959
108  COAP_OPT_PROXY_URI = 35, //RFC 7252
109  COAP_OPT_PROXY_SCHEME = 39, //RFC 7252
110  COAP_OPT_SIZE1 = 60, //RFC 7252
111  COAP_OPT_NO_RESPONSE = 258 //RFC 7967
113 
114 
115 /**
116  * @brief CoAP option formats
117  **/
118 
119 typedef enum
120 {
121  COAP_OPT_FORMAT_EMPTY = 0, ///<Zero-length sequence of bytes
122  COAP_OPT_FORMAT_OPAQUE = 1, ///<Opaque sequence of bytes
123  COAP_OPT_FORMAT_UINT = 2, ///<Non-negative integer
124  COAP_OPT_FORMAT_STRING = 3 ///<UTF-8 string
126 
127 
128 /**
129  * @brief Observe option
130  **/
131 
132 typedef enum
133 {
137 
138 
139 /**
140  * @brief Content-Format option
141  **/
142 
143 typedef enum
144 {
152 
153 
154 /**
155  * @brief Block size parameter
156  **/
157 
158 typedef enum
159 {
168 } CoapBlockSize;
169 
170 
171 /**
172  * @brief CoAP option
173  **/
174 
175 typedef struct
176 {
177  uint16_t delta;
178  uint16_t number;
179  size_t length;
180  const uint8_t *value;
181 } CoapOption;
182 
183 
184 /**
185  * @brief CoAP option parameters
186  **/
187 
188 typedef struct
189 {
190  uint16_t number; ///<Option number
191  bool_t critical; ///<Critical property
192  bool_t unsafe; ///<Unsafe property
193  bool_t noCacheKey; ///<NoCacheKey property
194  bool_t repeatable; ///<Repeatable option
195  const char_t *name; ///<Option name
196  CoapOptionFormat format; ///<Option format
197  uint16_t minLength; ///<Minimum acceptable length
198  uint16_t maxLength; ///<Maximum acceptable length
200 
201 
202 //CoAP option related functions
203 error_t coapParseOptions(const uint8_t *p, size_t length, size_t *consumed);
204 
205 error_t coapParseOption(const uint8_t *p, size_t length,
206  uint16_t prevOptionNum, CoapOption *option, size_t *consumed);
207 
208 error_t coapFormatOption(uint8_t *p, uint16_t prevOptionNum,
209  CoapOption *option, size_t *written);
210 
211 error_t coapSetOption(CoapMessage *message, uint16_t optionNum,
212  uint_t optionIndex, const uint8_t *optionValue, size_t optionLen);
213 
214 error_t coapSetUintOption(CoapMessage *message, uint16_t optionNum,
215  uint_t optionIndex, uint32_t optionValue);
216 
217 error_t coapGetOption(const CoapMessage *message, uint16_t optionNum,
218  uint_t optionIndex, const uint8_t **optionValue, size_t *optionLen);
219 
220 error_t coapGetUintOption(const CoapMessage *message, uint16_t optionNum,
221  uint_t optionIndex, uint32_t *optionValue);
222 
223 error_t coapDeleteOption(CoapMessage *message, uint16_t optionNum,
224  uint_t optionIndex);
225 
227  const char_t *optionValue, char_t separator);
228 
230  uint16_t optionNum, char_t *optionValue, size_t maxLen, char_t separator);
231 
232 const CoapOptionParameters *coapGetOptionParameters(uint16_t optionNum);
233 
234 //C++ guard
235 #ifdef __cplusplus
236 }
237 #endif
238 
239 #endif
error_t coapFormatOption(uint8_t *p, uint16_t prevOptionNum, CoapOption *option, size_t *written)
Format CoAP option.
Definition: coap_option.c:262
error_t coapGetOption(const CoapMessage *message, uint16_t optionNum, uint_t optionIndex, const uint8_t **optionValue, size_t *optionLen)
Get the value of the specified option.
Definition: coap_option.c:571
@ COAP_BLOCK_SIZE_256
Definition: coap_option.h:164
bool_t repeatable
Repeatable option.
Definition: coap_option.h:194
size_t length
Definition: coap_option.h:179
error_t coapParseOption(const uint8_t *p, size_t length, uint16_t prevOptionNum, CoapOption *option, size_t *consumed)
Parse CoAP option.
Definition: coap_option.c:133
uint8_t length
Definition: dtls_misc.h:149
uint16_t minLength
Minimum acceptable length.
Definition: coap_option.h:197
int bool_t
Definition: compiler_port.h:49
CoapOptionFormat format
Option format.
Definition: coap_option.h:196
@ COAP_OPT_ETAG
Definition: coap_option.h:94
@ COAP_CONTENT_FORMAT_APP_OCTET_STREAM
Definition: coap_option.h:148
@ COAP_OPT_LOCATION_PATH
Definition: coap_option.h:98
CoapOptionFormat
CoAP option formats.
Definition: coap_option.h:119
uint8_t p
Definition: ndp.h:298
uint16_t maxLength
Maximum acceptable length.
Definition: coap_option.h:198
@ COAP_OPT_FORMAT_UINT
Non-negative integer.
Definition: coap_option.h:123
bool_t noCacheKey
NoCacheKey property.
Definition: coap_option.h:193
uint16_t number
Definition: coap_option.h:178
@ COAP_BLOCK_SIZE_1024
Definition: coap_option.h:166
const char_t * name
Option name.
Definition: coap_option.h:195
CoapOptionNumber
CoAP options.
Definition: coap_option.h:90
@ COAP_OPT_CONTENT_FORMAT
Definition: coap_option.h:100
@ COAP_OPT_URI_HOST
Definition: coap_option.h:93
error_t coapDeleteOption(CoapMessage *message, uint16_t optionNum, uint_t optionIndex)
Remove an option from the specified CoAP message.
Definition: coap_option.c:688
CoAP message formatting and parsing.
CoapContentFormat
Content-Format option.
Definition: coap_option.h:143
@ COAP_OBSERVE_REGISTER
Definition: coap_option.h:134
@ COAP_OPT_FORMAT_STRING
UTF-8 string.
Definition: coap_option.h:124
@ COAP_CONTENT_FORMAT_APP_LINK_FORMAT
Definition: coap_option.h:146
@ COAP_OPT_URI_QUERY
Definition: coap_option.h:102
@ COAP_OPT_ACCEPT
Definition: coap_option.h:103
error_t
Error codes.
Definition: error.h:42
@ COAP_OPT_FORMAT_EMPTY
Zero-length sequence of bytes.
Definition: coap_option.h:121
error_t coapGetUintOption(const CoapMessage *message, uint16_t optionNum, uint_t optionIndex, uint32_t *optionValue)
Get the value of the specified uint option.
Definition: coap_option.c:651
@ COAP_OPT_PROXY_URI
Definition: coap_option.h:108
CoAP message.
Definition: coap_message.h:55
bool_t critical
Critical property.
Definition: coap_option.h:191
@ COAP_OPT_BLOCK1
Definition: coap_option.h:106
CoAP option parameters.
Definition: coap_option.h:188
@ COAP_CONTENT_FORMAT_APP_JSON
Definition: coap_option.h:150
@ COAP_OPT_OBSERVE
Definition: coap_option.h:96
@ COAP_BLOCK_SIZE_128
Definition: coap_option.h:163
@ COAP_OBSERVE_DEREGISTER
Definition: coap_option.h:135
@ COAP_CONTENT_FORMAT_APP_EXI
Definition: coap_option.h:149
@ COAP_OPT_PROXY_SCHEME
Definition: coap_option.h:109
const CoapOptionParameters * coapGetOptionParameters(uint16_t optionNum)
Retrieve parameters for a given option number.
Definition: coap_option.c:950
@ COAP_OPT_URI_PATH
Definition: coap_option.h:99
@ COAP_CONTENT_FORMAT_APP_XML
Definition: coap_option.h:147
error_t coapJoinRepeatableOption(const CoapMessage *message, uint16_t optionNum, char_t *optionValue, size_t maxLen, char_t separator)
Decode a path or query component from multiple repeatable options.
Definition: coap_option.c:877
@ COAP_OPT_SIZE1
Definition: coap_option.h:110
@ COAP_OPT_NO_RESPONSE
Definition: coap_option.h:111
char char_t
Definition: compiler_port.h:43
uint16_t number
Option number.
Definition: coap_option.h:190
@ COAP_BLOCK_SIZE_16
Definition: coap_option.h:160
@ COAP_OPT_MAX_AGE
Definition: coap_option.h:101
@ COAP_OPT_IF_NONE_MATCH
Definition: coap_option.h:95
@ COAP_OPT_URI_PORT
Definition: coap_option.h:97
@ COAP_OPT_LOCATION_QUERY
Definition: coap_option.h:104
bool_t unsafe
Unsafe property.
Definition: coap_option.h:192
const uint8_t * value
Definition: coap_option.h:180
@ COAP_OPT_BLOCK2
Definition: coap_option.h:105
uint8_t message[]
Definition: chap.h:152
CoapObserveOption
Observe option.
Definition: coap_option.h:132
@ COAP_OPT_FORMAT_OPAQUE
Opaque sequence of bytes.
Definition: coap_option.h:122
error_t coapParseOptions(const uint8_t *p, size_t length, size_t *consumed)
Parse the list of CoAP options.
Definition: coap_option.c:81
uint16_t delta
Definition: coap_option.h:177
@ COAP_CONTENT_FORMAT_TEXT_PLAIN
Definition: coap_option.h:145
@ COAP_BLOCK_SIZE_RESERVED
Definition: coap_option.h:167
CoAP option.
Definition: coap_option.h:175
@ COAP_BLOCK_SIZE_512
Definition: coap_option.h:165
@ COAP_OPT_SIZE2
Definition: coap_option.h:107
@ COAP_OPT_IF_MATCH
Definition: coap_option.h:92
unsigned int uint_t
Definition: compiler_port.h:45
TCP/IP stack core.
error_t coapSplitRepeatableOption(CoapMessage *message, uint16_t optionNum, const char_t *optionValue, char_t separator)
Encode a path or query component into multiple repeatable options.
Definition: coap_option.c:822
error_t coapSetOption(CoapMessage *message, uint16_t optionNum, uint_t optionIndex, const uint8_t *optionValue, size_t optionLen)
Add an option to the specified CoAP message.
Definition: coap_option.c:388
Definitions common to CoAP client and server.
CoapBlockSize
Block size parameter.
Definition: coap_option.h:158
@ COAP_BLOCK_SIZE_64
Definition: coap_option.h:162
error_t coapSetUintOption(CoapMessage *message, uint16_t optionNum, uint_t optionIndex, uint32_t optionValue)
Add a uint option to the specified CoAP message.
Definition: coap_option.c:543
@ COAP_BLOCK_SIZE_32
Definition: coap_option.h:161