csdk/libcoap-4.1.1/resource.h

   1 /* resource.h -- generic resource handling
   2  *
   3  * Copyright (C) 2010,2011,2014 Olaf Bergmann <bergmann@tzi.org>
   4  *
   5  * This file is part of the CoAP library libcoap. Please see
   6  * README for terms of use.
   7  */
   8
   9 /**
  10  * @file resource.h
  11  * @brief generic resource handling
  12  */
  13
  14 #ifndef _COAP_RESOURCE_H_
  15 #define _COAP_RESOURCE_H_
  16
  17 #include "config.h"
  18 #include "t_list.h"
  19
  20 #if defined(HAVE_ASSERT_H) && !defined(assert)
  21 # include <assert.h>
  22 #endif
  23
  24 #ifndef COAP_RESOURCE_CHECK_TIME
  25 /** The interval in seconds to check if resources have changed. */
  26 #define COAP_RESOURCE_CHECK_TIME 2
  27 #endif /* COAP_RESOURCE_CHECK_TIME */
  28
  29 #ifndef WITH_CONTIKI
  30 #  ifdef COAP_RESOURCES_NOHASH
  31 #    include "utlist.h"
  32 #  else
  33 #    include "uthash.h"
  34 #  endif
  35 #else /* WITH_CONTIKI */
  36 #endif /* WITH_CONTIKI */
  37 #include "hashkey.h"
  38 #include "async.h"
  39 #include "str.h"
  40 #include "pdu.h"
  41 #include "net.h"
  42 #include "subscribe.h"
  43
  44 /** Definition of message handler function (@sa coap_resource_t). */
  45 typedef void (*coap_method_handler_t)
  46   (coap_context_t  *, struct coap_resource_t *, coap_address_t *, coap_pdu_t *,
  47    str * /* token */, coap_pdu_t * /* response */);
  48
  49 #define COAP_ATTR_FLAGS_RELEASE_NAME  0x1
  50 #define COAP_ATTR_FLAGS_RELEASE_VALUE 0x2
  51
  52 typedef struct coap_attr_t {
  53   struct coap_attr_t *next;
  54   str name;
  55   str value;
  56   int flags;
  57 } coap_attr_t;
  58
  59 #define COAP_RESOURCE_FLAGS_RELEASE_URI 0x1
  60
  61 typedef struct coap_resource_t {
  62   unsigned int dirty:1;       /**< set to 1 if resource has changed */
  63   unsigned int partiallydirty:1; /**< set to 1 if some subscribers have not yet been notified of the last change */
  64   unsigned int observable:1; /**< can be observed */
  65   unsigned int cacheable:1;   /**< can be cached */
  66
  67   /**
  68    * Used to store handlers for the four coap methods @c GET, @c POST,
  69    * @c PUT, and @c DELETE. coap_dispatch() will pass incoming
  70    * requests to the handler that corresponds to its request method or
  71    * generate a 4.05 response if no handler is available.
  72    */
  73   coap_method_handler_t handler[4];
  74
  75   coap_key_t key;       /**< the actual key bytes for this resource */
  76
  77 #ifndef WITH_CONTIKI
  78 #ifdef COAP_RESOURCES_NOHASH
  79   struct coap_resource_t *next;
  80 #else
  81   UT_hash_handle hh;
  82 #endif
  83 #endif /* WITH_CONTIKI */
  84
  85 #ifndef WITH_CONTIKI
  86   coap_attr_t *link_attr; /**< attributes to be included with the link format */
  87 #else /* WITH_CONTIKI */
  88   LIST_STRUCT(link_attr); /**< attributes to be included with the link format */
  89 #endif /* WITH_CONTIKI */
  90   LIST_STRUCT(subscribers); /**< list of observers for this resource */
  91
  92
  93   /**
  94    * Request URI for this resource. This field will point into the
  95    * static memory. */
  96   str uri;
  97   int flags;
  98
  99 } coap_resource_t;
 100
 101 /**
 102  * Creates a new resource object and initializes the link field to the
 103  * string of length @p len.  This function returns the
 104  * new coap_resource_t object.
 105  *
 106  * @param uri    The URI path of the new resource.
 107  * @param len    The length of @p uri.
 108  * @param flags  Flags for memory management (in particular release of memory)
 109  *
 110  * @return A pointer to the new object or @c NULL on error.
 111  */
 112 coap_resource_t *coap_resource_init(const unsigned char *uri, size_t len, int flags);
 113
 114 /**
 115  * Registers the given @p resource for @p context. The resource must
 116  * have been created by coap_resource_init(), the storage allocated
 117  * for the resource will be released by coap_delete_resource().
 118  *
 119  * @param context  The context to use.
 120  * @param resource The resource to store.
 121  */
 122 void coap_add_resource(coap_context_t *context, coap_resource_t *resource);
 123
 124 /**
 125  * Deletes a resource identified by @p key. The storage allocated for
 126  * that resource is freed.
 127  *
 128  * @param context  The context where the resources are stored.
 129  * @param key      The unique key for the resource to delete.
 130  *
 131  * @return @c 1 if the resource was found (and destroyed), @c 0 otherwise.
 132  */
 133 int coap_delete_resource(coap_context_t *context, coap_key_t key);
 134
 135 /**
 136  * Registers a new attribute with the given @p resource. As the
 137  * attributes str fields will point to @p name and @p val the
 138  * caller must ensure that these pointers are valid during the
 139  * attribute's lifetime.
 140  *
 141  * @param resource  The resource to register the attribute with.
 142  * @param name      The attribute's name.
 143  * @param nlen      Length of @p name.
 144  * @param val       The attribute's value or @c NULL if none.
 145  * @param vlen      Length of @p val if specified.
 146  * @param flags     Flags for memory management (in particular release of memory)
 147  *
 148  * @return A pointer to the new attribute or @c NULL on error.
 149  */
 150 coap_attr_t *coap_add_attr(coap_resource_t *resource,
 151                            const unsigned char *name, size_t nlen,
 152                            const unsigned char *val, size_t vlen,
 153                            int flags);
 154
 155 /**
 156  * Returns @p resource's coap_attr_t object with given @p name if
 157  * found, @c NULL otherwise.
 158  *
 159  * @param resource  The resource to search for attribute @p name.
 160  * @param name      Name of the requested attribute.
 161  * @param nlen      Actual length of @p name.
 162  * @return The first attribute with specified @p name or @c NULL if
 163  *         none was found.
 164  */
 165 coap_attr_t *coap_find_attr(coap_resource_t *resource,
 166                             const unsigned char *name, size_t nlen);
 167
 168 /**
 169  * Deletes an attribute
 170  *
 171  * @param attr  Pointer to a previously created attribute
 172  *
 173  */
 174 void coap_delete_attr(coap_attr_t *attr);
 175
 176 /**
 177  * Status word to encode the result of conditional print or copy
 178  * operations such as coap_print_link(). The lower 28 bits of
 179  * coap_print_status_t are used to encode the number of characters
 180  * that has actually been printed, bits 28 to 31 encode the status.
 181  * When COAP_PRINT_STATUS_ERROR is set, an error occurred during
 182  * output. In this case, the other bits are undefined.
 183  * COAP_PRINT_STATUS_TRUNC indicates that the output is truncated,
 184  * i.e. the printing would have exceeded the current buffer.
 185  */
 186 typedef unsigned int coap_print_status_t;
 187
 188 #define COAP_PRINT_STATUS_MASK  0xF0000000u
 189 #define COAP_PRINT_OUTPUT_LENGTH(v) ((v) & ~COAP_PRINT_STATUS_MASK)
 190 #define COAP_PRINT_STATUS_ERROR 0x80000000u
 191 #define COAP_PRINT_STATUS_TRUNC 0x40000000u
 192
 193 /**
 194  * Writes a description of this resource in link-format to given text
 195  * buffer. @p len must be initialized to the maximum length of @p buf
 196  * and will be set to the number of characters actually written if
 197  * successful.  This function returns @c 1 on success or @c 0 on
 198  * error.
 199  *
 200  * @param resource The resource to describe.
 201  * @param buf      The output buffer to write the description to.
 202  * @param len      Must be initialized to the length of @p buf and
 203  *                 will be set to the length of the printed link description.
 204  * @param offset   The offset within the resource description where to
 205  *                 start writing into @p buf. This is useful for dealing
 206  *                 with the Block2 option. @p offset is updated during
 207  *                 output as it is consumed.
 208  *
 209  * @return If COAP_PRINT_STATUS_ERROR is set, an error occured. Otherwise,
 210  *         the lower 28 bits will indicate the number of characters that
 211  *         have actually been output into @p buffer. The flag
 212  *         COAP_PRINT_STATUS_TRUNC indicates that the output has been
 213  *         truncated.
 214  */
 215 coap_print_status_t coap_print_link(const coap_resource_t *resource,
 216                     unsigned char *buf, size_t *len, size_t *offset);
 217
 218 /**
 219  * Registers the specified @p handler as message handler for the request type
 220  * @p method
 221  *
 222  * @param resource The resource for which the handler shall be registered.
 223  * @param method   The CoAP request method to handle.
 224  * @param handler  The handler to register with @p resource.
 225  */
 226 static inline void
 227 coap_register_handler(coap_resource_t *resource,
 228                       unsigned char method, coap_method_handler_t handler) {
 229   assert(resource);
 230   assert(method > 0 && (size_t)(method-1) < sizeof(resource->handler)/sizeof(coap_method_handler_t));
 231   resource->handler[method-1] = handler;
 232 }
 233
 234 /**
 235  * Returns the resource identified by the unique string @p key. If no
 236  * resource was found, this function returns @c NULL.
 237  *
 238  * @param context  The context to look for this resource.
 239  * @param key      The unique key of the resource.
 240  *
 241  * @return A pointer to the resource or @c NULL if not found.
 242  */
 243 coap_resource_t *coap_get_resource_from_key(coap_context_t *context,
 244                                             coap_key_t key);
 245
 246 /**
 247  * Calculates the hash key for the resource requested by the
 248  * Uri-Options of @p request.  This function calls coap_hash() for
 249  * every path segment.
 250  *
 251  * @param request The requesting pdu.
 252  * @param key     The resulting hash is stored in @p key
 253  */
 254 void coap_hash_request_uri(const coap_pdu_t *request, coap_key_t key);
 255
 256 /**
 257  * @addtogroup observe
 258  */
 259
 260 /**
 261  * Adds the specified peer as observer for @p resource. The
 262  * subscription is identified by the given @p token. This function
 263  * returns the registered subscription information if the @p observer
 264  * has been added, or @c NULL on error.
 265  *
 266  * @param resource The observed resource.
 267  * @param observer The remote peer that wants to received status updates.
 268  * @param token The token that identifies this subscription.
 269  * @param token_length The actual length of @p token. Must be @c 0 when
 270  *        @p token is @c NULL.
 271  * @return A pointer to the added/updated subscription information or
 272  *        @c NULL on error.
 273  */
 274 coap_subscription_t *coap_add_observer(coap_resource_t *resource,
 275                                        const coap_address_t *observer,
 276                                        const str *token);
 277
 278 /**
 279  * Returns a subscription object for given @p peer.
 280  *
 281  * @param resource The observed resource.
 282  * @param peer The address to search for.
 283  * @param token The token that identifies this subscription or @c NULL for any
 284  *              token.
 285  * @return A valid subscription if exists or @c NULL otherwise.
 286  */
 287 coap_subscription_t *coap_find_observer(coap_resource_t *resource,
 288                                         const coap_address_t *peer,
 289                                         const str *token);
 290
 291 /**
 292  * Marks an observer as alive.
 293  *
 294  * @param context  The CoAP context to use
 295  * @param observer The transport address of the observer
 296  * @param token    The corresponding token that has been used for
 297  *   the subscription
 298  */
 299 void coap_touch_observer(coap_context_t *context,
 300                          const coap_address_t *observer,
 301                          const str *token);
 302
 303 /**
 304  * Removes any subscription for @p observer from @p resource and releases
 305  * the allocated storage.
 306  *
 307  * @param resource The observed resource.
 308  * @param observer The observer's address.
 309  * @param token    The token that identifies this subscription or @c NULL for any
 310  *                 token.
 311  */
 312 void coap_delete_observer(coap_resource_t *resource,
 313                           const coap_address_t *observer,
 314                           const str *token);
 315
 316 /**
 317  * Checks for all known resources, if they are dirty and notifies
 318  * subscribed observers.
 319  */
 320 void coap_check_notify(coap_context_t *context);
 321
 322 /** @} */
 323
 324 #endif /* _COAP_RESOURCE_H_ */