1 /* 2 * async.h -- state management for asynchronous messages 3 * 4 * Copyright (C) 2010-2011 Olaf Bergmann <bergmann@tzi.org> 5 * 6 * SPDX-License-Identifier: BSD-2-Clause 7 * 8 * This file is part of the CoAP library libcoap. Please see README for terms 9 * of use. 10 */ 11 12 /** 13 * @file async.h 14 * @brief State management for asynchronous messages 15 */ 16 17 #ifndef COAP_ASYNC_H_ 18 #define COAP_ASYNC_H_ 19 20 #include "net.h" 21 22 /** 23 * @defgroup coap_async Asynchronous Messaging 24 * @{ 25 * API functions for Async "separate" messages. 26 * A coap_context_t object holds a list of coap_async_t objects that can 27 * be used to generate a separate response in the case a result of a request 28 * cannot be delivered immediately. 29 */ 30 31 /** 32 * Returns @c 1 if libcoap was built with separate messages enabled, 33 * @c 0 otherwise. 34 */ 35 int coap_async_is_supported(void); 36 37 /** 38 * Allocates a new coap_async_t object and fills its fields according to 39 * the given @p request. This function returns a pointer to the registered 40 * coap_async_t object or @c NULL on error. Note that this function will 41 * return @c NULL in case that an object with the same identifier is already 42 * registered. 43 * 44 * When the delay expires, a copy of the @p request will get sent to the 45 * appropriate request handler. 46 * 47 * @param session The session that is used for asynchronous transmissions. 48 * @param request The request that is handled asynchronously. 49 * @param delay The amount of time to delay before sending response, 0 means 50 * wait forever. 51 * 52 * @return A pointer to the registered coap_async_t object or @c 53 * NULL in case of an error. 54 */ 55 coap_async_t * 56 coap_register_async(coap_session_t *session, 57 const coap_pdu_t *request, 58 coap_tick_t delay); 59 60 /** 61 * Update the delay timeout, so changing when the registered @p async triggers. 62 * 63 * When the new delay expires, a copy of the original request will get sent to 64 * the appropriate request handler. 65 * 66 * @param async The object to update. 67 * @param delay The amount of time to delay before sending response, 0 means 68 * wait forever. 69 */ 70 void 71 coap_async_set_delay(coap_async_t *async, coap_tick_t delay); 72 73 /** 74 * Releases the memory that was allocated by coap_register_async() for the 75 * object @p async. 76 * 77 * @param session The session to use. 78 * @param async The object to delete. 79 */ 80 void 81 coap_free_async(coap_session_t *session, coap_async_t *async); 82 83 /** 84 * Retrieves the object identified by @p token from the list of asynchronous 85 * transactions that are registered with @p context. This function returns a 86 * pointer to that object or @c NULL if not found. 87 * 88 * @param session The session that is used for asynchronous transmissions. 89 * @param token The PDU's token of the object to retrieve. 90 * 91 * @return A pointer to the object identified by @p token or @c NULL if 92 * not found. 93 */ 94 coap_async_t *coap_find_async(coap_session_t *session, coap_bin_const_t token); 95 96 /** 97 * Set the application data pointer held in @p async. This overwrites any 98 * existing data pointer. 99 * 100 * @param async The async state object. 101 * @param app_data The pointer to the data. 102 */ 103 void coap_async_set_app_data(coap_async_t *async, void *app_data); 104 105 /** 106 * Gets the application data pointer held in @p async. 107 * 108 * @param async The async state object. 109 * 110 * @return The applicaton data pointer. 111 */ 112 void *coap_async_get_app_data(const coap_async_t *async); 113 114 /** @} */ 115 116 #endif /* COAP_ASYNC_H_ */ 117