1 /* subscribe.h -- subscription handling for CoAP
2 * see draft-hartke-coap-observe-03
4 * Copyright (C) 2010--2012 Olaf Bergmann <bergmann@tzi.org>
6 * This file is part of the CoAP library libcoap. Please see
7 * README for terms of use.
10 #ifndef _COAP_SUBSCRIBE_H_
11 #define _COAP_SUBSCRIBE_H_
17 * @defgroup observe Resource observation
21 #ifndef COAP_OBS_MAX_NON
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.
27 #define COAP_OBS_MAX_NON 5
28 #endif /* COAP_OBS_MAX_NON */
30 #ifndef COAP_OBS_MAX_FAIL
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.
36 #define COAP_OBS_MAX_FAIL 3
37 #endif /* COAP_OBS_MAX_FAIL */
39 /** Subscriber information */
40 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 */
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) */
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;
55 void coap_subscription_init(coap_subscription_t *);
65 typedef unsigned long coap_key_t;
67 /** Used to indicate that a hashkey is invalid. */
68 #define COAP_INVALID_HASHKEY ((coap_key_t)-1)
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 */
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) */
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
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
96 * The return value indicates the result code that should be used in a response to
99 int (*data)(coap_uri_t *uri, unsigned char *mediatype, unsigned int offset, unsigned char *buf, unsigned int *buflen, int *finished);
105 coap_key_t resource; /* hash key for subscribed resource */
106 time_t expires; /* expiry time of subscription */
108 coap_address_t subscriber; /**< subscriber's address */
110 str token; /**< subscription token */
111 }coap_subscription_t;
113 #define COAP_RESOURCE(node) ((coap_resource_t *)(node)->data)
114 #define COAP_SUBSCRIPTION(node) ((coap_subscription_t *)(node)->data)
116 /** Checks subscribed resources for updates and notifies subscribers of changes. */
117 void coap_check_resource_list(coap_context_t *context);
119 /** Removes expired subscriptions. */
120 void coap_check_subscriptions(coap_context_t *context);
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().
128 coap_key_t coap_add_resource(coap_context_t *context, coap_resource_t *);
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).
134 int coap_delete_resource(coap_context_t *context, coap_key_t key);
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,
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.
155 coap_key_t coap_add_subscription(coap_context_t *context,
156 coap_subscription_t *subscription);
159 * Returns the subscription from subscriber for the resource identified
160 * by hashkey. When token is not NULL the subscription must have the
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.
169 coap_subscription_t * coap_find_subscription(coap_context_t *context,
171 struct sockaddr *subscriber,
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.
180 int coap_delete_subscription(coap_context_t *context,
182 struct sockaddr *subscriber);
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);
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);
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);
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);
201 #endif /* _COAP_SUBSCRIBE_H_ */