* Copyright (C) 2010-2013 Olaf Bergmann <bergmann@tzi.org>
*
* This file is part of the CoAP library libcoap. Please see
- * README for terms of use.
+ * README for terms of use.
*/
/**
#include "bits.h"
#include "pdu.h"
-/**
+/**
* Use byte-oriented access methods here because sliding a complex
* struct coap_opt_t over the data buffer may cause bus error on
* certain platforms.
unsigned char *value;
} coap_option_t;
+
+/** Representation of the association between a CoAP option key and its
+ * data type and valid data length ranges.
+ */
+typedef struct
+{
+ unsigned short key; /**< The ID of the option the following values apply to. */
+ unsigned char type; /**< The type of the option: u=uint, s=string, o=opaque. */
+ unsigned int min; /**< The minimum number of bytes allowed for the option data */
+ unsigned int max; /**< The maximum number of bytes allowed for the option data */
+} coap_option_def_t;
+
/**
* Parses the option pointed to by @p opt into @p result. This
* function returns the number of bytes that have been parsed, or @c 0
* on error. An error is signaled when illegal delta or length values
* are encountered or when option parsing would result in reading past
- * the option (i.e. beyond opt + length).
+ * the option (i.e. beyond opt + length).
*
* @param opt The beginning of the option to parse.
* @param length The maximum length of @p opt.
/**
* Calculates the beginning of the PDU's option section.
- *
+ *
* @param pdu The PDU containing the options.
* @return A pointer to the first option if available, or @c NULL otherwise.
*/
-coap_opt_t *options_start(coap_pdu_t *pdu);
+coap_opt_t *options_start(coap_pdu_t *pdu, coap_transport_type transport);
/**
* Interprets @p opt as pointer to a CoAP option and advances to
* @{
*/
-/**
+/**
* Fixed-size bit-vector we use for option filtering. It is large
* enough to hold the highest option number known at build time (20 in
* the core spec).
/** Pre-defined filter that includes all options. */
#define COAP_OPT_ALL NULL
-/**
+/**
* Clears filter @p f.
- *
+ *
* @param f The filter to clear.
*/
static inline void coap_option_filter_clear(coap_opt_filter_t f)
memset(f, 0, sizeof(coap_opt_filter_t));
}
-/**
+/**
* Sets the corresponding bit for @p type in @p filter. This function
* returns @c 1 if bit was set or @c -1 on error (i.e. when the given
* type does not fit in the filter).
- *
+ *
* @param filter The filter object to change.
- * @param type The type for which the bit should be set.
- *
+ * @param type The type for which the bit should be set.
+ *
* @return @c 1 if bit was set, @c -1 otherwise.
*/
inline static int coap_option_setb(coap_opt_filter_t filter, unsigned short type)
return bits_setb((uint8_t *) filter, sizeof(coap_opt_filter_t), type);
}
-/**
+/**
* Clears the corresponding bit for @p type in @p filter. This function
* returns @c 1 if bit was cleared or @c -1 on error (i.e. when the given
* type does not fit in the filter).
- *
+ *
* @param filter The filter object to change.
- * @param type The type for which the bit should be cleared.
- *
+ * @param type The type for which the bit should be cleared.
+ *
* @return @c 1 if bit was set, @c -1 otherwise.
*/
inline static int coap_option_clrb(coap_opt_filter_t filter, unsigned short type)
return bits_clrb((uint8_t *) filter, sizeof(coap_opt_filter_t), type);
}
-/**
+/**
* Gets the corresponding bit for @p type in @p filter. This function
* returns @c 1 if the bit is set @c 0 if not, or @c -1 on error (i.e.
* when the given type does not fit in the filter).
- *
+ *
* @param filter The filter object to read bit from..
* @param type The type for which the bit should be read.
- *
+ *
* @return @c 1 if bit was set, @c 0 if not, @c -1 on error.
*/
inline static int coap_option_getb(const coap_opt_filter_t filter, unsigned short type)
return bits_getb((uint8_t *) filter, sizeof(coap_opt_filter_t), type);
}
-/**
+/**
* Iterator to run through PDU options. This object must be
* initialized with coap_option_iterator_init(). Call
* coap_option_next() to walk through the list of options until
coap_opt_filter_t filter; /**< option filter */
} coap_opt_iterator_t;
-/**
+/**
* Initializes the given option iterator @p oi to point to the
* beginning of the @p pdu's option list. This function returns @p oi
* on success, @c NULL otherwise (i.e. when no options exist).
* Note that a length check on the option list must be performed before
* coap_option_iterator_init() is called.
- *
+ *
* @param pdu The PDU the options of which should be walked through.
* @param oi An iterator object that will be initilized.
- * @param filter An optional option type filter.
- * With @p type != @c COAP_OPT_ALL, coap_option_next()
- * will return only options matching this bitmask.
+ * @param filter An optional option type filter.
+ * With @p type != @c COAP_OPT_ALL, coap_option_next()
+ * will return only options matching this bitmask.
* Fence-post options @c 14, @c 28, @c 42, ... are always
* skipped.
- *
+ *
* @return The iterator object @p oi on success, @c NULL otherwise.
*/
coap_opt_iterator_t *coap_option_iterator_init(coap_pdu_t *pdu, coap_opt_iterator_t *oi,
- const coap_opt_filter_t filter);
+ const coap_opt_filter_t filter, coap_transport_type transport);
-/**
+/**
* Updates the iterator @p oi to point to the next option. This
* function returns a pointer to that option or @c NULL if no more
* options exist. The contents of @p oi will be updated. In
* oi->option points to the beginning of the current option
* itself. When advanced past the last option, @c oi->option will be
* @c NULL.
- *
+ *
* Note that options are skipped whose corresponding bits in the
* filter specified with coap_option_iterator_init() are @c 0. Options
* with type codes that do not fit in this filter hence will always be
* returned.
- *
+ *
* @param oi The option iterator to update.
- *
+ *
* @return The next option or @c NULL if no more options exist.
*/
coap_opt_t *coap_option_next(coap_opt_iterator_t *oi);
-/**
+/**
* Retrieves the first option of type @p type from @p pdu. @p oi must
* point to a coap_opt_iterator_t object that will be initialized by
* this function to filter only options with code @p type. This
* function returns the first option with this type, or @c NULL if not
* found.
- *
+ *
* @param pdu The PDU to parse for options.
* @param type The option type code to search for.
* @param oi An iterator object to use.
- *
- * @return A pointer to the first option of type @p type, or @c NULL
+ *
+ * @return A pointer to the first option of type @p type, or @c NULL
* if not found.
*/
coap_opt_t *coap_check_option(coap_pdu_t *pdu, unsigned char type, coap_opt_iterator_t *oi);
* indicates by how many bytes @p opt must be advanced to encode the
* option value.
*
- * @param opt The option buffer space where @p delta and @p length are
+ * @param opt The option buffer space where @p delta and @p length are
* written
* @param maxlen The maximum length of @p opt
* @param delta The actual delta value to encode.
#define COAP_OPT_DELTA(opt) coap_opt_delta(opt)
/** @deprecated { Use coap_opt_encode() instead. } */
-#define COAP_OPT_SETDELTA(opt,val) \
+#ifndef WITH_TCP
+#define COAP_OPT_SETDELTA(opt,val) \
coap_opt_encode((opt), COAP_MAX_PDU_SIZE, (val), NULL, 0)
-
+#endif
/**
* Returns the length of the given option. @p opt must point to an
* option jump or the beginning of the option. This function returns
/**
* Returns a pointer to the value of the given option. @p opt must
- * point to an option jump or the beginning of the option. This
+ * point to an option jump or the beginning of the option. This
* function returns @c NULL if @p opt is not a valid option.
*
* @param opt The option whose value should be returned.
*/
unsigned char *coap_opt_value(coap_opt_t *opt);
+/**
+ * Returns a pointer to the coap option range definitions. @key
+ * must be a valid option ID. This function returns @c NULL if
+ * @p key is not a valid option ID.
+ *
+ * @param key The option ID whose definition should be returned.
+ * @return A pointer to the option definition.
+ */
+coap_option_def_t* coap_opt_def(unsigned short key);
+
/** @deprecated { Use coap_opt_value() instead. } */
#define COAP_OPT_VALUE(opt) coap_opt_value((coap_opt_t *)opt)