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