1 /* async.h -- state management for asynchronous messages
3 * Copyright (C) 2010,2011 Olaf Bergmann <bergmann@tzi.org>
5 * This file is part of the CoAP library libcoap. Please see
6 * README for terms of use.
11 * @brief state management for asynchronous messages
15 #ifndef _COAP_ASYNC_H_
16 #define _COAP_ASYNC_H_
24 * @defgroup coap_async Asynchronous Messaging
26 * Structure for managing asynchronous state of CoAP resources. A
27 * coap_resource_t object holds a list of coap_async_state_t objects
28 * that can be used to generate a separate response in case a result
29 * of an operation cannot be delivered in time, or the resource has
30 * been explicitly subscribed to with the option @c observe.
32 typedef struct coap_async_state_t {
33 unsigned char flags; /**< holds the flags to control behaviour */
36 * Holds the internal time when the object was registered with a
37 * resource. This field will be updated whenever
38 * coap_register_async() is called for a specific resource.
43 * This field can be used to register opaque application data with
44 * the asynchronous state object. */
47 unsigned short message_id; /**< id of last message seen */
48 coap_tid_t id; /**< transaction id */
50 struct coap_async_state_t *next; /**< internally used for linking */
52 coap_address_t peer; /**< the peer to notify */
53 size_t tokenlen; /**< length of the token */
54 #if defined(__GNUC__) && !defined(__clang__) && !defined(__INTEL_COMPILER)
55 #pragma GCC diagnostic push
56 #pragma GCC diagnostic ignored "-pedantic"
58 __extension__ unsigned char token[]; /**< the token to use in a response */
59 #if defined(__GNUC__) && !defined(__clang__) && !defined(__INTEL_COMPILER)
60 #pragma GCC diagnostic pop
64 /* Definitions for Async Status Flags These flags can be used to
65 * control the behaviour of asynchronous response generation. */
66 #define COAP_ASYNC_CONFIRM 0x01 /**< send confirmable response */
67 #define COAP_ASYNC_SEPARATE 0x02 /**< send separate response */
68 #define COAP_ASYNC_OBSERVED 0x04 /**< the resource is being observed */
70 /** release application data on destruction */
71 #define COAP_ASYNC_RELEASE_DATA 0x08
74 * Allocates a new coap_async_state_t object and fills its fields
75 * according to the given @p request. The @p flags are used to control
76 * generation of empty ACK responses to stop retransmissions and to
77 * release registered @p data when the resource is deleted by
78 * coap_free_async(). This function returns a pointer to the registered
79 * coap_async_t object or @c NULL on error. Note that this function will
80 * return @c NULL in case that an object with the same identifier is
83 * @param context The context to use.
84 * @param peer The remote peer that is to be asynchronously notified.
85 * @param request The request that is handled asynchronously.
86 * @param flags Flags to control state management.
87 * @param data Opaque application data to register. Note that the
88 * storage occupied by @p data is released on destruction
89 * only if flag COAP_ASYNC_RELEASE_DATA is set.
91 * @return A pointer to the registered coap_async_state_t object or
92 * @c NULL in case of an error.
95 coap_register_async(coap_context_t *context, coap_address_t *peer,
96 coap_pdu_t *request, unsigned char flags, void *data);
99 * Removes the state object identified by @p id from @p context. The
100 * removed object is returned in @p s, if found. Otherwise, @p s is
101 * undefined. This function returns @c 1 if the object was removed, @c
102 * 0 otherwise. Note that the storage allocated for the stored object
103 * is not released by this functions. You will have to call
104 * coap_free_async() to do so.
106 * @param context The context where the async object is registered.
107 * @param id The identifier of the asynchronous transaction.
108 * @param s Will be set to the object identified by @p id
111 * @return @c 1 if object was removed and @p s updated, or @c 0 if no
112 * object was found with the given id. @p s is valid only if the
113 * return value is @c 1.
115 int coap_remove_async(coap_context_t *context, coap_tid_t id,
116 coap_async_state_t **s);
119 * Releases the memory that was allocated by coap_async_state_init()
120 * for the object @p s. The registered application data will be
121 * released automatically if COAP_ASYNC_RELEASE_DATA is set.
123 * @param s The object to delete.
126 coap_free_async(coap_async_state_t *state);
129 * Retrieves the object identified by @p id from the list of asynchronous
130 * transactions that are registered with @p context. This function returns
131 * a pointer to that object or @c NULL if not found.
133 * @param context The context where the asynchronous objects are
135 * @param id The id of the object to retrieve.
137 * @return A pointer to the object identified by @p id or @c NULL if
140 coap_async_state_t *coap_find_async(coap_context_t *context, coap_tid_t id);
143 * Updates the time stamp of @p s.
145 * @param s The state object to update.
148 coap_touch_async(coap_async_state_t *s) { coap_ticks(&s->created); }
152 #endif /* WITHOUT_ASYNC */
154 #endif /* _COAP_ASYNC_H_ */