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 */
36int 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 */
56coap_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 */
70void 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 */
80void 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 */
89void 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 */
102coap_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 */
111void 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 */
120void *coap_async_get_app_data(const coap_async_t *async);
121
122/** @} */
123
124#endif /* COAP_ASYNC_H_ */
125