2 * option.h -- helpers for handling options in CoAP PDUs
4 * Copyright (C) 2010-2013 Olaf Bergmann <bergmann@tzi.org>
6 * This file is part of the CoAP library libcoap. Please see
7 * README for terms of use.
12 * @brief helpers for handling options in CoAP PDUs
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
26 typedef unsigned char coap_opt_t;
27 #define PCHAR(p) ((coap_opt_t *)(p))
29 /** Representation of CoAP options. */
38 /** Representation of the association between a CoAP option key and its
39 * data type and valid data length ranges.
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 */
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).
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.
62 size_t coap_opt_parse(const coap_opt_t *opt, size_t length, coap_option_t *result);
65 * Returns the size of the given option, taking into account a
66 * possible option jump.
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.
74 size_t coap_opt_size(const coap_opt_t *opt);
76 /** @deprecated { Use coap_opt_size() instead. } */
77 #define COAP_OPT_SIZE(opt) coap_opt_size(opt)
80 * Calculates the beginning of the PDU's option section.
82 * @param pdu The PDU containing the options.
83 * @return A pointer to the first option if available, or @c NULL otherwise.
85 coap_opt_t *options_start(coap_pdu_t *pdu, coap_transport_t transport);
88 * Interprets @p opt as pointer to a CoAP option and advances to
89 * the next byte past this option.
92 #define options_next(opt) \
93 ((coap_opt_t *)((unsigned char *)(opt) + COAP_OPT_SIZE(opt)))
96 * @defgroup opt_filter Option Filters
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
105 typedef unsigned char coap_opt_filter_t[(COAP_MAX_OPT >> 3) + 1];
107 /** Pre-defined filter that includes all options. */
108 #define COAP_OPT_ALL NULL
111 * Clears filter @p f.
113 * @param f The filter to clear.
115 INLINE_API void coap_option_filter_clear(coap_opt_filter_t f)
117 memset(f, 0, sizeof(coap_opt_filter_t));
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).
125 * @param filter The filter object to change.
126 * @param type The type for which the bit should be set.
128 * @return @c 1 if bit was set, @c -1 otherwise.
130 INLINE_API int coap_option_setb(coap_opt_filter_t filter, unsigned short type)
132 return bits_setb((uint8_t *) filter, sizeof(coap_opt_filter_t), type);
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).
140 * @param filter The filter object to change.
141 * @param type The type for which the bit should be cleared.
143 * @return @c 1 if bit was set, @c -1 otherwise.
145 INLINE_API int coap_option_clrb(coap_opt_filter_t filter, unsigned short type)
147 return bits_clrb((uint8_t *) filter, sizeof(coap_opt_filter_t), type);
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).
155 * @param filter The filter object to read bit from..
156 * @param type The type for which the bit should be read.
158 * @return @c 1 if bit was set, @c 0 if not, @c -1 on error.
160 INLINE_API int coap_option_getb(const coap_opt_filter_t filter, unsigned short type)
162 return bits_getb((uint8_t *) filter, sizeof(coap_opt_filter_t), type);
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.
172 * coap_opt_t *option;
173 * coap_opt_iterator_t opt_iter;
174 * coap_option_iterator_init(pdu, &opt_iter, COAP_OPT_ALL);
176 * while ((option = coap_option_next(&opt_iter))) {
177 * ... do something with option ...
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;
192 * Initializes the given option iterator @p oi to point to the beginning of the
193 * @p pdu's option list. This function returns @p oi on success, @c NULL
194 * otherwise (i.e. when no options exist). Note that a length check on the
195 * option list must be performed before coap_option_iterator_init() is called.
197 * @param pdu The PDU the options of which should be walked through.
198 * @param oi An iterator object that will be initilized.
199 * @param filter An optional option type filter.
200 * With @p type != @c COAP_OPT_ALL, coap_option_next()
201 * will return only options matching this bitmask.
202 * Fence-post options @c 14, @c 28, @c 42, ... are always
205 * @return The iterator object @p oi on success, @c NULL otherwise.
207 coap_opt_iterator_t *coap_option_iterator_init(coap_pdu_t *pdu,
208 coap_opt_iterator_t *oi,
209 const coap_opt_filter_t filter);
212 * Initializes the given option iterator @p oi to point to the
213 * beginning of the @p pdu's option list. This function returns @p oi
214 * on success, @c NULL otherwise (i.e. when no options exist).
215 * Note that a length check on the option list must be performed before
216 * coap_option_iterator_init() is called.
218 * @param pdu The PDU the options of which should be walked through.
219 * @param oi An iterator object that will be initilized.
220 * @param filter An optional option type filter.
221 * With @p type != @c COAP_OPT_ALL, coap_option_next()
222 * will return only options matching this bitmask.
223 * Fence-post options @c 14, @c 28, @c 42, ... are always
226 * @return The iterator object @p oi on success, @c NULL otherwise.
228 coap_opt_iterator_t *coap_option_iterator_init2(coap_pdu_t *pdu, coap_opt_iterator_t *oi,
229 const coap_opt_filter_t filter, coap_transport_t transport);
232 * Updates the iterator @p oi to point to the next option. This
233 * function returns a pointer to that option or @c NULL if no more
234 * options exist. The contents of @p oi will be updated. In
235 * particular, @c oi->n specifies the current option's ordinal number
236 * (counted from @c 1), @c oi->type is the option's type code, and @c
237 * oi->option points to the beginning of the current option
238 * itself. When advanced past the last option, @c oi->option will be
241 * Note that options are skipped whose corresponding bits in the
242 * filter specified with coap_option_iterator_init() are @c 0. Options
243 * with type codes that do not fit in this filter hence will always be
246 * @param oi The option iterator to update.
248 * @return The next option or @c NULL if no more options exist.
250 coap_opt_t *coap_option_next(coap_opt_iterator_t *oi);
253 * Retrieves the first option of type @p type from @p pdu. @p oi must
254 * point to a coap_opt_iterator_t object that will be initialized by
255 * this function to filter only options with code @p type. This
256 * function returns the first option with this type, or @c NULL if not
259 * @param pdu The PDU to parse for options.
260 * @param type The option type code to search for.
261 * @param oi An iterator object to use.
263 * @return A pointer to the first option of type @p type, or @c NULL
266 coap_opt_t *coap_check_option(coap_pdu_t *pdu, unsigned char type, coap_opt_iterator_t *oi);
269 * Encodes the given delta and length values into @p opt. This
270 * function returns the number of bytes that were required to encode
271 * @p delta and @p length or @c 0 on error. Note that the result
272 * indicates by how many bytes @p opt must be advanced to encode the
275 * @param opt The option buffer space where @p delta and @p length are
277 * @param maxlen The maximum length of @p opt
278 * @param delta The actual delta value to encode.
279 * @param length The actual length value to encode.
280 * @return The number of bytes used or @c 0 on error.
282 size_t coap_opt_setheader(coap_opt_t *opt, size_t maxlen, unsigned short delta, size_t length);
285 * Encodes option with given @p delta into @p opt. This function returns
286 * the number of bytes written to @p opt or @c 0 on error. This happens
287 * especially when @p opt does not provide sufficient space to store
288 * the option value, delta, and option jumps when required.
290 * @param opt The option buffer space where @p val is written
291 * @param n Maximum length of @p opt.
292 * @param delta The option delta.
293 * @param val The option value to copy into @p opt.
294 * @param len The actual length of @p val.
295 * @return The number of bytes that have been written to @p opt or
296 * @c 0 on error. The return value will always be less than @p n.
298 size_t coap_opt_encode(coap_opt_t *opt, size_t n, unsigned short delta, const unsigned char *val,
302 * Decodes the delta value of the next option. This function returns
303 * the number of bytes read or @c 0 on error. The caller of this
304 * function must ensure that it does not read over the boundaries
305 * of @p opt (e.g. by calling coap_opt_check_delta().
307 * @param opt The option to examine
308 * @return The number of bytes read or @c 0 on error.
310 unsigned short coap_opt_delta(const coap_opt_t *opt);
312 /** @deprecated { Use coap_opt_delta() instead. } */
313 #define COAP_OPT_DELTA(opt) coap_opt_delta(opt)
315 /** @deprecated { Use coap_opt_encode() instead. } */
317 #define COAP_OPT_SETDELTA(opt,val) \
318 coap_opt_encode((opt), COAP_MAX_PDU_SIZE, (val), NULL, 0)
321 * Returns the length of the given option. @p opt must point to an
322 * option jump or the beginning of the option. This function returns
323 * @c 0 when @p opt is not an option or the actual length of @p opt
324 * (which can be @c 0 as well).
326 * @note {The rationale for using @c 0 in case of an error is that in
327 * most contexts, the result of this function is used to skip the next
328 * coap_opt_length() bytes. }
330 * @param opt The option whose length should be returned.
331 * @return The option's length or @c 0 when undefined.
333 unsigned short coap_opt_length(const coap_opt_t *opt);
335 /** @deprecated { Use coap_opt_length() instead. } */
336 #define COAP_OPT_LENGTH(opt) coap_opt_length(opt)
339 * Returns a pointer to the value of the given option. @p opt must
340 * point to an option jump or the beginning of the option. This
341 * function returns @c NULL if @p opt is not a valid option.
343 * @param opt The option whose value should be returned.
344 * @return A pointer to the option value or @c NULL on error.
346 unsigned char *coap_opt_value(coap_opt_t *opt);
349 * Returns a pointer to the coap option range definitions. @key
350 * must be a valid option ID. This function returns @c NULL if
351 * @p key is not a valid option ID.
353 * @param key The option ID whose definition should be returned.
354 * @return A pointer to the option definition.
356 coap_option_def_t* coap_opt_def(unsigned short key);
358 /** @deprecated { Use coap_opt_value() instead. } */
359 #define COAP_OPT_VALUE(opt) coap_opt_value((coap_opt_t *)opt)
363 #endif /* _OPTION_H_ */