|
| 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 |
| 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_ */ |
0 commit comments