1 /*
2 * async.h -- state management for asynchronous messages
3 *
4 * Copyright (C) 2010-2011 Olaf Bergmann <bergmann@tzi.org>
5 *
6 * This file is part of the CoAP library libcoap. Please see README for terms
7 * of use.
8 */
9
10 /**
11 * @file async.h
12 * @brief State management for asynchronous messages
13 */
14
15 #ifndef COAP_ASYNC_H_
16 #define COAP_ASYNC_H_
17
18 #include "net.h"
19
20 #ifndef WITHOUT_ASYNC
21
22 /**
23 * @defgroup coap_async Asynchronous Messaging
24 * @{
25 * Structure for managing asynchronous state of CoAP resources. A
26 * coap_resource_t object holds a list of coap_async_state_t objects that can be
27 * used to generate a separate response in case a result of an operation cannot
28 * be delivered in time, or the resource has been explicitly subscribed to with
29 * the option @c observe.
30 */
31 typedef struct coap_async_state_t {
32 unsigned char flags; /**< holds the flags to control behaviour */
33
34 /**
35 * Holds the internal time when the object was registered with a
36 * resource. This field will be updated whenever
37 * coap_register_async() is called for a specific resource.
38 */
39 coap_tick_t created;
40
41 /**
42 * This field can be used to register opaque application data with the
43 * asynchronous state object.
44 */
45 void *appdata;
46 coap_session_t *session; /**< transaction session */
47 coap_tid_t id; /**< transaction id */
48 struct coap_async_state_t *next; /**< internally used for linking */
49 size_t tokenlen; /**< length of the token */
50 uint8_t token[8]; /**< the token to use in a response */
51 } coap_async_state_t;
52
53 /* Definitions for Async Status Flags These flags can be used to control the
54 * behaviour of asynchronous response generation.
55 */
56 #define COAP_ASYNC_CONFIRM 0x01 /**< send confirmable response */
57 #define COAP_ASYNC_SEPARATE 0x02 /**< send separate response */
58 #define COAP_ASYNC_OBSERVED 0x04 /**< the resource is being observed */
59
60 /** release application data on destruction */
61 #define COAP_ASYNC_RELEASE_DATA 0x08
62
63 /**
64 * Allocates a new coap_async_state_t object and fills its fields according to
65 * the given @p request. The @p flags are used to control generation of empty
66 * ACK responses to stop retransmissions and to release registered @p data when
67 * the resource is deleted by coap_free_async(). This function returns a pointer
68 * to the registered coap_async_t object or @c NULL on error. Note that this
69 * function will return @c NULL in case that an object with the same identifier
70 * is already registered.
71 *
72 * @param context The context to use.
73 * @param session The session that is used for asynchronous transmissions.
74 * @param request The request that is handled asynchronously.
75 * @param flags Flags to control state management.
76 * @param data Opaque application data to register. Note that the
77 * storage occupied by @p data is released on destruction
78 * only if flag COAP_ASYNC_RELEASE_DATA is set.
79 *
80 * @return A pointer to the registered coap_async_state_t object or @c
81 * NULL in case of an error.
82 */
83 coap_async_state_t *
84 coap_register_async(coap_context_t *context,
85 coap_session_t *session,
86 coap_pdu_t *request,
87 unsigned char flags,
88 void *data);
89
90 /**
91 * Removes the state object identified by @p id from @p context. The removed
92 * object is returned in @p s, if found. Otherwise, @p s is undefined. This
93 * function returns @c 1 if the object was removed, @c 0 otherwise. Note that
94 * the storage allocated for the stored object is not released by this
95 * functions. You will have to call coap_free_async() to do so.
96 *
97 * @param context The context where the async object is registered.
98 * @param session The session that is used for asynchronous transmissions.
99 * @param id The identifier of the asynchronous transaction.
100 * @param s Will be set to the object identified by @p id after removal.
101 *
102 * @return @c 1 if object was removed and @p s updated, or @c 0 if no
103 * object was found with the given id. @p s is valid only if the
104 * return value is @c 1.
105 */
106 int coap_remove_async(coap_context_t *context,
107 coap_session_t *session,
108 coap_tid_t id,
109 coap_async_state_t **s);
110
111 /**
112 * Releases the memory that was allocated by coap_async_state_init() for the
113 * object @p s. The registered application data will be released automatically
114 * if COAP_ASYNC_RELEASE_DATA is set.
115 *
116 * @param state The object to delete.
117 */
118 void
119 coap_free_async(coap_async_state_t *state);
120
121 /**
122 * Retrieves the object identified by @p id from the list of asynchronous
123 * transactions that are registered with @p context. This function returns a
124 * pointer to that object or @c NULL if not found.
125 *
126 * @param context The context where the asynchronous objects are registered
127 * with.
128 * @param session The session that is used for asynchronous transmissions.
129 * @param id The id of the object to retrieve.
130 *
131 * @return A pointer to the object identified by @p id or @c NULL if
132 * not found.
133 */
134 coap_async_state_t *coap_find_async(coap_context_t *context, coap_session_t *session, coap_tid_t id);
135
136 /**
137 * Updates the time stamp of @p s.
138 *
139 * @param s The state object to update.
140 */
141 COAP_STATIC_INLINE void
coap_touch_async(coap_async_state_t * s)142 coap_touch_async(coap_async_state_t *s) { coap_ticks(&s->created); }
143
144 /** @} */
145
146 #endif /* WITHOUT_ASYNC */
147
148 #endif /* COAP_ASYNC_H_ */
149