csdk/libcoap-4.1.1/subscribe.h

   1 /* subscribe.h -- subscription handling for CoAP
   2  *                see draft-hartke-coap-observe-03
   3  *
   4  * Copyright (C) 2010--2012 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 #ifndef _COAP_SUBSCRIBE_H_
  12 #define _COAP_SUBSCRIBE_H_
  13
  14 #include "config.h"
  15 #include "address.h"
  16
  17 /**
  18  * @defgroup observe Resource observation
  19  * @{
  20  */
  21
  22 #ifndef COAP_OBS_MAX_NON
  23 /**
  24  * Number of notifications that may be sent non-confirmable before a
  25  * confirmable message is sent to detect if observers are alive. The
  26  * maximum allowed value here is @c 15.
  27  */
  28 #define COAP_OBS_MAX_NON   5
  29 #endif /* COAP_OBS_MAX_NON */
  30
  31 #ifndef COAP_OBS_MAX_FAIL
  32 /**
  33  * Number of confirmable notifications that may fail (i.e. time out
  34  * without being ACKed) before an observer is removed. The maximum
  35  * value for COAP_OBS_MAX_FAIL is @c 3.
  36  */
  37 #define COAP_OBS_MAX_FAIL  3
  38 #endif /* COAP_OBS_MAX_FAIL */
  39
  40 /** Subscriber information */
  41 typedef struct coap_subscription_t {
  42   struct coap_subscription_t *next; /**< next element in linked list */
  43   coap_address_t subscriber;        /**< address and port of subscriber */
  44
  45   unsigned int non:1;           /**< send non-confirmable notifies if @c 1  */
  46   unsigned int non_cnt:4;       /**< up to 15 non-confirmable notifies allowed */
  47   unsigned int fail_cnt:2;      /**< up to 3 confirmable notifies can fail */
  48   unsigned int dirty:1;         /**< set if the notification temporarily could not be sent (in that case, the resource's partiallydirty flag is set too) */
  49
  50   size_t token_length;          /**< actual length of token */
  51   unsigned char token[8];       /**< token used for subscription */
  52   /* @todo CON/NON flag, block size */
  53 } coap_subscription_t;
  54
  55 void coap_subscription_init(coap_subscription_t *);
  56
  57 #if 0
  58 #include "uthash.h"
  59 #include "uri.h"
  60 #include "list.h"
  61 #include "pdu.h"
  62 #include "net.h"
  63
  64 #if 0
  65 typedef unsigned long coap_key_t;
  66
  67 /** Used to indicate that a hashkey is invalid. */
  68 #define COAP_INVALID_HASHKEY ((coap_key_t)-1)
  69
  70 typedef struct {
  71   coap_uri_t *uri;              /* unique identifier; memory is released by coap_delete_resource() */
  72   UT_hash_handle hh;            /**< hash handle (for internal use only) */
  73   str *name;                    /* display name of the resource */
  74   unsigned char mediatype;      /* media type for resource representation */
  75   unsigned int dirty:1;         /* set to 1 if resource has changed */
  76   unsigned int writable:1;      /* set to 1 if resource can be changed using PUT */
  77
  78   /* cache-control */
  79   unsigned char etag[4];        /* version identifier for this resource
  80                                  * (zero terminated, first byte is zero if not set). */
  81   unsigned int maxage;          /* maximum cache time (zero means no Max-age option) */
  82
  83   /**
  84    * Callback function that copies the resource representation into the provided data
  85    * buffer (PDU payload). finished is set to 1 to indicate that this was the last block
  86    * of buflen data for this resource representation, 0 means that data is not finished
  87    * and a subsequent call with offset updated by buflen would yield more data (i.e.
  88    * the M-bit of CoAP's block option must be set if offset and buflen are selected
  89    * accordingly.
  90    * When called, buflen must be set to the maximum length of buf that is to be filled
  91    * with the mediatype representation of the resource identified by uri.
  92    * The mediatype must be set to the requested mediatype of COAP_MEDIATYPE_ANY if
  93    * none was given. On return, the mediatype will be set to the type that is
  94    * actually used.
  95    * The return value indicates the result code that should be used in a response to
  96    * this function.
  97    */
  98   int (*data)(coap_uri_t *uri, unsigned char *mediatype, unsigned int offset, unsigned char *buf, unsigned int *buflen, int *finished);
  99 } coap_resource_t;
 100 #endif
 101
 102 typedef struct {
 103   coap_key_t resource;          /* hash key for subscribed resource */
 104   time_t expires;               /* expiry time of subscription */
 105
 106   coap_address_t subscriber;    /**< subscriber's address */
 107
 108   str token;                    /**< subscription token */
 109 } coap_subscription_t;
 110
 111 #define COAP_RESOURCE(node) ((coap_resource_t *)(node)->data)
 112 #define COAP_SUBSCRIPTION(node) ((coap_subscription_t *)(node)->data)
 113
 114 /** Checks subscribed resources for updates and notifies subscribers of changes. */
 115 void coap_check_resource_list(coap_context_t *context);
 116
 117 /** Removes expired subscriptions. */
 118 void coap_check_subscriptions(coap_context_t *context);
 119
 120 #if 0
 121 /**
 122  * Adds specified resource to the resource observation list. Returns a
 123  * unique key for the resource. The alloceted memory is released when
 124  * the resource is destroyed with coap_delete_resource().
 125  */
 126 coap_key_t coap_add_resource(coap_context_t *context, coap_resource_t *);
 127
 128 /**
 129  * Deletes the resource that is identified by key. Returns 1 if the resource was
 130  * removed, 0 on error (e.g. if no such resource exists).
 131  */
 132 int coap_delete_resource(coap_context_t *context, coap_key_t key);
 133 #endif
 134 /**
 135  * Creates a new subscription object filled with the given data. The storage
 136  * allocated for this object must be released using coap_free(). */
 137 coap_subscription_t *coap_new_subscription(coap_context_t *context,
 138                                            const coap_uri_t *resource,
 139                                            const struct sockaddr *subscriber,
 140                                            socklen_t addrlen,
 141                                            time_t expiry);
 142
 143 /**
 144  * Adds the given subsription object to the observer list.
 145  * @param context The CoAP context
 146  * @param subscription A new subscription oobject created with coap_new_subscription()
 147  * @return A unique hash key for this resource or COAP_INVALID_HASHKEY on error.
 148  * The storage allocated for the subscription object is released when it is
 149  * removed from the subscription list, unless the function has returned
 150  * COAP_INVALID_HASHKEY. In this case, the storage must be released by the
 151  * caller of this function.
 152 */
 153 coap_key_t coap_add_subscription(coap_context_t *context,
 154                                  coap_subscription_t *subscription);
 155
 156 /**
 157  * Returns the subscription from subscriber for the resource identified
 158  * by hashkey. When token is not NULL the subscription must have the
 159  * same token.
 160  * @param context The CoAP context
 161  * @param hashkey The unique key that identifies the subscription
 162  * @param subscriber The subscriber's transport address
 163  * @param token If not NULL, this specifies a token given by the
 164  *              subscriber to identify its subscription.
 165  * @return The requested subscription object or NULL when not found.
 166  */
 167 coap_subscription_t * coap_find_subscription(coap_context_t *context,
 168                                              coap_key_t hashkey,
 169                                              struct sockaddr *subscriber,
 170                                              str *token);
 171 /**
 172  * Removes a subscription from the subscription list stored in context and
 173  * releases the storage that was allocated for this subscription.
 174  * @param context The CoAP context.
 175  * @param haskey The unique key that identifies the subscription to remove.
 176  * @return 1 if a subscription was removed, 0 otherwise.
 177  */
 178 int coap_delete_subscription(coap_context_t *context,
 179                              coap_key_t hashkey,
 180                              struct sockaddr *subscriber);
 181
 182 /** Returns a unique hash for the specified URI or COAP_INVALID_HASHKEY on error. */
 183 coap_key_t coap_uri_hash(const coap_uri_t *uri);
 184
 185
 186 /** Returns a unique hash for the specified subscription or COAP_INVALID_HASHKEY on error. */
 187 coap_key_t coap_subscription_hash(coap_subscription_t *subscription);
 188 #if 0
 189 /** Returns the resource identified by key or NULL if not found. */
 190 coap_resource_t *coap_get_resource_from_key(coap_context_t *ctx, coap_key_t key);
 191
 192 /** Returns the resource identified by uri or NULL if not found. */
 193 coap_resource_t *coap_get_resource(coap_context_t *ctx, coap_uri_t *uri);
 194 #endif
 195
 196 #endif
 197
 198 /** @} */
 199
 200 #endif /* _COAP_SUBSCRIBE_H_ */