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   unsigned short message_id;       /**< id of last message seen */
47   coap_tid_t id;                   /**< transaction id */
48   struct coap_async_state_t *next; /**< internally used for linking */
49   coap_address_t peer;             /**< the peer to notify */
50   size_t tokenlen;                 /**< length of the token */
51   unsigned char token[];           /**< the token to use in a response */
52 } coap_async_state_t;
53 
54 /* Definitions for Async Status Flags These flags can be used to control the
55  * behaviour of asynchronous response generation.
56  */
57 #define COAP_ASYNC_CONFIRM   0x01  /**< send confirmable response */
58 #define COAP_ASYNC_SEPARATE  0x02  /**< send separate response */
59 #define COAP_ASYNC_OBSERVED  0x04  /**< the resource is being observed */
60 
61 /** release application data on destruction */
62 #define COAP_ASYNC_RELEASE_DATA  0x08
63 
64 /**
65  * Allocates a new coap_async_state_t object and fills its fields according to
66  * the given @p request. The @p flags are used to control generation of empty
67  * ACK responses to stop retransmissions and to release registered @p data when
68  * the resource is deleted by coap_free_async(). This function returns a pointer
69  * to the registered coap_async_t object or @c NULL on error. Note that this
70  * function will return @c NULL in case that an object with the same identifier
71  * is already registered.
72  *
73  * @param context  The context to use.
74  * @param peer     The remote peer that is to be asynchronously notified.
75  * @param request  The request that is handled asynchronously.
76  * @param flags    Flags to control state management.
77  * @param data     Opaque application data to register. Note that the
78  *                 storage occupied by @p data is released on destruction
79  *                 only if flag COAP_ASYNC_RELEASE_DATA is set.
80  *
81  * @return         A pointer to the registered coap_async_state_t object or @c
82  *                 NULL in case of an error.
83  */
84 coap_async_state_t *
85 coap_register_async(coap_context_t *context,
86                     coap_address_t *peer,
87                     coap_pdu_t *request,
88                     unsigned char flags,
89                     void *data);
90 
91 /**
92  * Removes the state object identified by @p id from @p context. The removed
93  * object is returned in @p s, if found. Otherwise, @p s is undefined. This
94  * function returns @c 1 if the object was removed, @c 0 otherwise. Note that
95  * the storage allocated for the stored object is not released by this
96  * functions. You will have to call coap_free_async() to do so.
97  *
98  * @param context The context where the async object is registered.
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_tid_t id,
108                       coap_async_state_t **s);
109 
110 /**
111  * Releases the memory that was allocated by coap_async_state_init() for the
112  * object @p s. The registered application data will be released automatically
113  * if COAP_ASYNC_RELEASE_DATA is set.
114  *
115  * @param state The object to delete.
116  */
117 void
118 coap_free_async(coap_async_state_t *state);
119 
120 /**
121  * Retrieves the object identified by @p id from the list of asynchronous
122  * transactions that are registered with @p context. This function returns a
123  * pointer to that object or @c NULL if not found.
124  *
125  * @param context The context where the asynchronous objects are registered
126  *                with.
127  * @param id      The id of the object to retrieve.
128  *
129  * @return        A pointer to the object identified by @p id or @c NULL if
130  *                not found.
131  */
132 coap_async_state_t *coap_find_async(coap_context_t *context, coap_tid_t id);
133 
134 /**
135  * Updates the time stamp of @p s.
136  *
137  * @param s The state object to update.
138  */
139 static inline void
coap_touch_async(coap_async_state_t * s)140 coap_touch_async(coap_async_state_t *s) { coap_ticks(&s->created); }
141 
142 /** @} */
143 
144 #endif /*  WITHOUT_ASYNC */
145 
146 #endif /* _COAP_ASYNC_H_ */
147