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