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