Imported Upstream version 1.1.1
[platform/upstream/iotivity.git] / resource / csdk / connectivity / lib / libcoap-4.1.1 / option.h
1 /*
2  * option.h -- helpers for handling options in CoAP PDUs
3  *
4  * Copyright (C) 2010-2013 Olaf Bergmann <bergmann@tzi.org>
5  *
6  * This file is part of the CoAP library libcoap. Please see
7  * README for terms of use.
8  */
9
10 /**
11  * @file option.h
12  * @brief helpers for handling options in CoAP PDUs
13  */
14
15 #ifndef _OPTION_H_
16 #define _OPTION_H_
17
18 #include "bits.h"
19 #include "pdu.h"
20
21 /**
22  * Use byte-oriented access methods here because sliding a complex
23  * struct coap_opt_t over the data buffer may cause bus error on
24  * certain platforms.
25  */
26 typedef unsigned char coap_opt_t;
27 #define PCHAR(p) ((coap_opt_t *)(p))
28
29 /** Representation of CoAP options. */
30 typedef struct
31 {
32     unsigned short delta;
33     size_t length;
34     unsigned char *value;
35 } coap_option_t;
36
37
38 /** Representation of the association between a CoAP option key and its
39  *  data type and valid data length ranges.
40  */
41 typedef struct
42 {
43     unsigned short key;     /**< The ID of the option the following values apply to. */
44     unsigned char type;     /**< The type of the option: u=uint, s=string, o=opaque. */
45     unsigned int min;       /**< The minimum number of bytes allowed for the option data */
46     unsigned int max;       /**< The maximum number of bytes allowed for the option data */
47 } coap_option_def_t;
48
49 /**
50  * Parses the option pointed to by @p opt into @p result. This
51  * function returns the number of bytes that have been parsed, or @c 0
52  * on error. An error is signaled when illegal delta or length values
53  * are encountered or when option parsing would result in reading past
54  * the option (i.e. beyond opt + length).
55  *
56  * @param opt    The beginning of the option to parse.
57  * @param length The maximum length of @p opt.
58  * @param result A pointer to the coap_option_t structure that is
59  *               filled with actual values iff coap_opt_parse() > 0.
60  * @return The number of bytes parsed or @c 0 on error.
61  */
62 size_t coap_opt_parse(const coap_opt_t *opt, size_t length, coap_option_t *result);
63
64 /**
65  * Returns the size of the given option, taking into account a
66  * possible option jump.
67  *
68  * @param opt An option jump or the beginning of the option.
69  * @return The number of bytes between @p opt and the end of
70  *         the option starting at @p opt. In case of an error,
71  *         this function returns @c 0 as options need at least
72  *         one byte storage space.
73  */
74 size_t coap_opt_size(const coap_opt_t *opt);
75
76 /** @deprecated { Use coap_opt_size() instead. } */
77 #define COAP_OPT_SIZE(opt) coap_opt_size(opt)
78
79 /**
80  * Calculates the beginning of the PDU's option section.
81  *
82  * @param pdu The PDU containing the options.
83  * @return A pointer to the first option if available, or @c NULL otherwise.
84  */
85 coap_opt_t *options_start(coap_pdu_t *pdu, coap_transport_type transport);
86
87 /**
88  * Interprets @p opt as pointer to a CoAP option and advances to
89  * the next byte past this option.
90  * @hideinitializer
91  */
92 #define options_next(opt) \
93   ((coap_opt_t *)((unsigned char *)(opt) + COAP_OPT_SIZE(opt)))
94
95 /**
96  * @defgroup opt_filter Option Filters
97  * @{
98  */
99
100 /**
101  * Fixed-size bit-vector we use for option filtering. It is large
102  * enough to hold the highest option number known at build time (20 in
103  * the core spec).
104  */
105 typedef unsigned char coap_opt_filter_t[(COAP_MAX_OPT >> 3) + 1];
106
107 /** Pre-defined filter that includes all options. */
108 #define COAP_OPT_ALL NULL
109
110 /**
111  * Clears filter @p f.
112  *
113  * @param f The filter to clear.
114  */
115 static inline void coap_option_filter_clear(coap_opt_filter_t f)
116 {
117     memset(f, 0, sizeof(coap_opt_filter_t));
118 }
119
120 /**
121  * Sets the corresponding bit for @p type in @p filter. This function
122  * returns @c 1 if bit was set or @c -1 on error (i.e. when the given
123  * type does not fit in the filter).
124  *
125  * @param filter The filter object to change.
126  * @param type   The type for which the bit should be set.
127  *
128  * @return @c 1 if bit was set, @c -1 otherwise.
129  */
130 inline static int coap_option_setb(coap_opt_filter_t filter, unsigned short type)
131 {
132     return bits_setb((uint8_t *) filter, sizeof(coap_opt_filter_t), type);
133 }
134
135 /**
136  * Clears the corresponding bit for @p type in @p filter. This function
137  * returns @c 1 if bit was cleared or @c -1 on error (i.e. when the given
138  * type does not fit in the filter).
139  *
140  * @param filter The filter object to change.
141  * @param type   The type for which the bit should be cleared.
142  *
143  * @return @c 1 if bit was set, @c -1 otherwise.
144  */
145 inline static int coap_option_clrb(coap_opt_filter_t filter, unsigned short type)
146 {
147     return bits_clrb((uint8_t *) filter, sizeof(coap_opt_filter_t), type);
148 }
149
150 /**
151  * Gets the corresponding bit for @p type in @p filter. This function
152  * returns @c 1 if the bit is set @c 0 if not, or @c -1 on error (i.e.
153  * when the given type does not fit in the filter).
154  *
155  * @param filter The filter object to read bit from..
156  * @param type   The type for which the bit should be read.
157  *
158  * @return @c 1 if bit was set, @c 0 if not, @c -1 on error.
159  */
160 inline static int coap_option_getb(const coap_opt_filter_t filter, unsigned short type)
161 {
162     return bits_getb((uint8_t *) filter, sizeof(coap_opt_filter_t), type);
163 }
164
165 /**
166  * Iterator to run through PDU options. This object must be
167  * initialized with coap_option_iterator_init(). Call
168  * coap_option_next() to walk through the list of options until
169  * coap_option_next() returns @c NULL.
170  *
171  * @code
172  * coap_opt_t *option;
173  * coap_opt_iterator_t opt_iter;
174  * coap_option_iterator_init(pdu, &opt_iter, COAP_OPT_ALL);
175  *
176  * while ((option = coap_option_next(&opt_iter))) {
177  *   ... do something with option ...
178  * }
179  * @endcode
180  */
181 typedef struct
182 {
183     size_t length; /**< remaining length of PDU */
184     unsigned short type; /**< decoded option type */
185     unsigned int bad :1; /**< iterator object is ok if not set */
186     unsigned int filtered :1; /**< denotes whether or not filter is used */
187     coap_opt_t *next_option; /**< pointer to the unparsed next option */
188     coap_opt_filter_t filter; /**< option filter */
189 } coap_opt_iterator_t;
190
191 /**
192  * Initializes the given option iterator @p oi to point to the
193  * beginning of the @p pdu's option list. This function returns @p oi
194  * on success, @c NULL otherwise (i.e. when no options exist).
195  * Note that a length check on the option list must be performed before
196  * coap_option_iterator_init() is called.
197  *
198  * @param pdu  The PDU the options of which should be walked through.
199  * @param oi   An iterator object that will be initilized.
200  * @param filter An optional option type filter.
201  *               With @p type != @c COAP_OPT_ALL, coap_option_next()
202  *               will return only options matching this bitmask.
203  *               Fence-post options @c 14, @c 28, @c 42, ... are always
204  *               skipped.
205  *
206  * @return The iterator object @p oi on success, @c NULL otherwise.
207  */
208 coap_opt_iterator_t *coap_option_iterator_init(coap_pdu_t *pdu, coap_opt_iterator_t *oi,
209         const coap_opt_filter_t filter, coap_transport_type transport);
210
211 /**
212  * Updates the iterator @p oi to point to the next option. This
213  * function returns a pointer to that option or @c NULL if no more
214  * options exist. The contents of @p oi will be updated. In
215  * particular, @c oi->n specifies the current option's ordinal number
216  * (counted from @c 1), @c oi->type is the option's type code, and @c
217  * oi->option points to the beginning of the current option
218  * itself. When advanced past the last option, @c oi->option will be
219  * @c NULL.
220  *
221  * Note that options are skipped whose corresponding bits in the
222  * filter specified with coap_option_iterator_init() are @c 0. Options
223  * with type codes that do not fit in this filter hence will always be
224  * returned.
225  *
226  * @param oi The option iterator to update.
227  *
228  * @return The next option or @c NULL if no more options exist.
229  */
230 coap_opt_t *coap_option_next(coap_opt_iterator_t *oi);
231
232 /**
233  * Retrieves the first option of type @p type from @p pdu. @p oi must
234  * point to a coap_opt_iterator_t object that will be initialized by
235  * this function to filter only options with code @p type. This
236  * function returns the first option with this type, or @c NULL if not
237  * found.
238  *
239  * @param pdu  The PDU to parse for options.
240  * @param type The option type code to search for.
241  * @param oi   An iterator object to use.
242  *
243  * @return A pointer to the first option of type @p type, or @c NULL
244  *         if not found.
245  */
246 coap_opt_t *coap_check_option(coap_pdu_t *pdu, unsigned char type, coap_opt_iterator_t *oi);
247
248 /**
249  * Encodes the given delta and length values into @p opt. This
250  * function returns the number of bytes that were required to encode
251  * @p delta and @p length or @c 0 on error. Note that the result
252  * indicates by how many bytes @p opt must be advanced to encode the
253  * option value.
254  *
255  * @param opt    The option buffer space where @p delta and @p length are
256  *               written
257  * @param maxlen The maximum length of @p opt
258  * @param delta The actual delta value to encode.
259  * @param length The actual length value to encode.
260  * @return The number of bytes used or @c 0 on error.
261  */
262 size_t coap_opt_setheader(coap_opt_t *opt, size_t maxlen, unsigned short delta, size_t length);
263
264 /**
265  * Encodes option with given @p delta into @p opt. This function returns
266  * the number of bytes written to @p opt or @c 0 on error. This happens
267  * especially when @p opt does not provide sufficient space to store
268  * the option value, delta, and option jumps when required.
269  *
270  * @param opt   The option buffer space where @p val is written
271  * @param n     Maximum length of @p opt.
272  * @param delta The option delta.
273  * @param val   The option value to copy into @p opt.
274  * @param len   The actual length of @p val.
275  * @return The number of bytes that have been written to @p opt or
276  *         @c 0 on error. The return value will always be less than @p n.
277  */
278 size_t coap_opt_encode(coap_opt_t *opt, size_t n, unsigned short delta, const unsigned char *val,
279         size_t length);
280
281 /**
282  * Decodes the delta value of the next option. This function returns
283  * the number of bytes read or @c 0 on error. The caller of this
284  * function must ensure that it does not read over the boundaries
285  * of @p opt (e.g. by calling coap_opt_check_delta().
286  *
287  * @param opt The option to examine
288  * @return The number of bytes read or @c 0 on error.
289  */
290 unsigned short coap_opt_delta(const coap_opt_t *opt);
291
292 /** @deprecated { Use coap_opt_delta() instead. } */
293 #define COAP_OPT_DELTA(opt) coap_opt_delta(opt)
294
295 /** @deprecated { Use coap_opt_encode() instead. } */
296 #ifndef WITH_TCP
297 #define COAP_OPT_SETDELTA(opt,val)          \
298   coap_opt_encode((opt), COAP_MAX_PDU_SIZE, (val), NULL, 0)
299 #endif
300 /**
301  * Returns the length of the given option. @p opt must point to an
302  * option jump or the beginning of the option. This function returns
303  * @c 0 when @p opt is not an option or the actual length of @p opt
304  * (which can be @c 0 as well).
305  *
306  * @note {The rationale for using @c 0 in case of an error is that in
307  * most contexts, the result of this function is used to skip the next
308  * coap_opt_length() bytes. }
309  *
310  * @param opt  The option whose length should be returned.
311  * @return The option's length or @c 0 when undefined.
312  */
313 unsigned short coap_opt_length(const coap_opt_t *opt);
314
315 /** @deprecated { Use coap_opt_length() instead. } */
316 #define COAP_OPT_LENGTH(opt) coap_opt_length(opt)
317
318 /**
319  * Returns a pointer to the value of the given option. @p opt must
320  * point to an option jump or the beginning of the option. This
321  * function returns @c NULL if @p opt is not a valid option.
322  *
323  * @param opt  The option whose value should be returned.
324  * @return A pointer to the option value or @c NULL on error.
325  */
326 unsigned char *coap_opt_value(coap_opt_t *opt);
327
328 /**
329  * Returns a pointer to the coap option range definitions. @key
330  * must be a valid option ID. This function returns @c NULL if
331  * @p key is not a valid option ID.
332  *
333  * @param key The option ID whose definition should be returned.
334  * @return A pointer to the option definition.
335  */
336 coap_option_def_t* coap_opt_def(unsigned short key);
337
338 /** @deprecated { Use coap_opt_value() instead. } */
339 #define COAP_OPT_VALUE(opt) coap_opt_value((coap_opt_t *)opt)
340
341 /** @} */
342
343 #endif /* _OPTION_H_ */