1 /*
2  * coap_async.h -- state management for asynchronous messages
3  *
4  * Copyright (C) 2010-2023 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 coap_async.h
14  * @brief State management for asynchronous messages
15  */
16 
17 #ifndef COAP_ASYNC_H_
18 #define COAP_ASYNC_H_
19 
20 #include "coap_net.h"
21 
22 /**
23  * @ingroup application_api
24  * @defgroup coap_async Asynchronous Messaging
25  * @{
26  * API for delayed "separate" messages.
27  * A coap_context_t object holds a list of coap_async_t objects that can
28  * be used to generate a separate response in the case a result of a request
29  * cannot be delivered immediately.
30  */
31 
32 /**
33  * Returns @c 1 if libcoap was built with separate messages enabled,
34  * @c 0 otherwise.
35  */
36 int coap_async_is_supported(void);
37 
38 /**
39  * Allocates a new coap_async_t object and fills its fields according to
40  * the given @p request. This function returns a pointer to the registered
41  * coap_async_t object or @c NULL on error. Note that this function will
42  * return @c NULL in case that an object with the same identifier is already
43  * registered.
44  *
45  * When the delay expires, a copy of the @p request will get sent to the
46  * appropriate request handler.
47  *
48  * @param session  The session that is used for asynchronous transmissions.
49  * @param request  The request that is handled asynchronously.
50  * @param delay    The amount of time to delay before sending response, 0 means
51  *                 wait forever.
52  *
53  * @return         A pointer to the registered coap_async_t object or @c
54  *                 NULL in case of an error.
55  */
56 coap_async_t *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 coap_async_set_delay(coap_async_t *async, coap_tick_t delay);
71 
72 /**
73  * Trigger the registered @p async.
74  *
75  * A copy of the original request will get sent to the appropriate request
76  * handler.
77  *
78  * @param async The async object to trigger.
79  */
80 void coap_async_trigger(coap_async_t *async);
81 
82 /**
83  * Releases the memory that was allocated by coap_register_async() for the
84  * object @p async.
85  *
86  * @param session  The session to use.
87  * @param async The object to delete.
88  */
89 void coap_free_async(coap_session_t *session, coap_async_t *async);
90 
91 /**
92  * Retrieves the object identified by @p token from the list of asynchronous
93  * transactions that are registered with @p context. This function returns a
94  * pointer to that object or @c NULL if not found.
95  *
96  * @param session The session that is used for asynchronous transmissions.
97  * @param token   The PDU's token of the object to retrieve.
98  *
99  * @return        A pointer to the object identified by @p token or @c NULL if
100  *                not found.
101  */
102 coap_async_t *coap_find_async(coap_session_t *session, coap_bin_const_t token);
103 
104 /**
105  * Set the application data pointer held in @p async. This overwrites any
106  * existing data pointer.
107  *
108  * @param async The async state object.
109  * @param app_data The pointer to the data.
110  */
111 void coap_async_set_app_data(coap_async_t *async, void *app_data);
112 
113 /**
114  * Gets the application data pointer held in @p async.
115  *
116  * @param async The async state object.
117  *
118  * @return The applicaton data pointer.
119  */
120 void *coap_async_get_app_data(const coap_async_t *async);
121 
122 /** @} */
123 
124 #endif /* COAP_ASYNC_H_ */
125