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