1COAP_ASYNC(3) libcoap Manual COAP_ASYNC(3)
2
6 coap_async, coap_async_is_supported, coap_register_async,
7 coap_async_trigger, coap_async_set_delay, coap_find_async,
8 coap_free_async, coap_async_set_app_data, coap_async_get_app_data -
9 Work with CoAP async support
10
12 #include <coap3/coap.h>
13 int coap_async_is_supported(void);
15 coap_async_t *coap_register_async(coap_session_t *session, const
17 coap_pdu_t *request, coap_tick_t delay);
18 void coap_async_trigger(coap_async_t *async);
20 void coap_async_set_delay(coap_async_t *async, coap_tick_t delay);
22 void coap_free_async(coap_session_t *session, coap_async_t *async);
24 coap_async_t *coap_find_async(coap_session_t *session, coap_bin_const_t
26 token);
27 void coap_async_set_app_data(coap_async_t *async, void *app_data);
29 void *coap_async_get_app_data(const coap_async_t *async);
31 For specific (D)TLS library support, link with -lcoap-3-notls,
33 -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or
34 -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default
35 (D)TLS library support.
36
38 CoAP server responses can be piggybacked ("RFC7252 5.2.1. Piggybacked")
39 or separate ("RFC7252 5.2.2. Separate").
40 For piggybacked responses, the response packet contains both the status
42 and any data.
43 For separate responses, there is an initial empty ACK response
45 (Confirmable only - to stop the client re-transmitting the request)
46 followed at a later time by a packet containing the status and any
47 data.
48 Usually responses are piggybacked, but this man page focuses on a
50 mechanism for providing separate (async) support.
51 NOTE: If a server is providing Proxy support, then the server code
53 should return from the request handler with no response code set (i.e.
54 respond with empty ACK) and then send back the response as provided by
55 the upstream server when received, so no need to use the async support.
56
58 Function: coap_async_is_supported()
59 The coap_async_is_supported() function is used to determine if there is
61 async support or not compiled into libcoap.
62 Function: coap_register_async()
64 The coap_register_async() function is used to set up an asynchronous
66 delayed request for the request PDU associated with the session. The
67 application request handler will get called with a copy of request
68 after delay ticks which will then cause a response to be sent. If delay
69 is 0, then the application request handler will not get called until
70 coap_async_trigger() or coap_async_set_delay() is called.
71 Function: coap_async_trigger()
73 The coap_async_trigger() function is used to expire the delay for the
75 async definition, so the application request handler is almost
76 immediately called.
77 Function: coap_async_set_delay()
79 The coap_async_set_delay() function is used to update the remaining
81 delay before the application request handler is called for the async
82 definition. If delay is set to 0, then the application request handler
83 will not get called.
84 An example of usage here is coap_register_async() sets delay to 0, and
86 then when the response is ready at an indeterminate point in the
87 future, coap_async_set_delay() is called setting delay to 1.
88 Alternatively, coap_async_trigger() can be called.
89 Function: coap_free_async()
91 The coap_free_async() function is used to delete an async definition.
93 Function: coap_find_async()
95 The coap_find_async() function is used to determine if there is an
97 async definition based on the session and token token.
98 Function: coap_async_set_app_data()
100 The coap_async_set_app_data() function is used to add in user defined
102 app_data to the async definition. It is the responsibility of the
103 application to release this data if appropriate. This would usually be
104 done when the application request handler is called under async
105 control.
106 Function: coap_async_get_app_data()
108 The coap_async_get_app_data() function is used to retrieve any defined
110 application data from the async definition.
111
113 coap_async_is_supported() returns 1 if support is available, 0
114 otherwise.
115 coap_register_async() and coap_find_async() return a pointer to an
117 async definition or NULL if there is an error.
118 coap_async_get_app_data() returns a pointer to the user defined data.
120
122 CoAP Server Non-Encrypted Setup
123 #include <coap3/coap.h>
125 /*
127 * This example is used to demonstrate how to set up and use a "separate"
128 * response (empty ACK followed by data response at a later stage).
129 */
130 static void
131 hnd_get_with_delay(coap_session_t *session,
132 coap_resource_t *resource,
133 coap_pdu_t *request,
134 coap_string_t *query,
135 coap_pdu_t *response) {
136 unsigned long delay = 5;
137 size_t size;
138 coap_async_t *async;
139 coap_bin_const_t token = coap_pdu_get_token(request);
140 /*
142 * See if this is the initial, or delayed request
143 */
144 async = coap_find_async(session, token);
146 if (!async) {
147 /* Set up an async request to trigger delay in the future */
148 if (query) {
149 const uint8_t *p = query->s;
150 delay = 0;
152 for (size = query->length; size; --size, ++p)
153 delay = delay * 10 + (*p - '0');
154 if (delay == 0) {
155 coap_log_info("async: delay of 0 not supported\n");
156 coap_pdu_set_code(response, COAP_RESPONSE_CODE_BAD_REQUEST);
157 return;
158 }
159 }
160 async = coap_register_async(session,
161 request,
162 COAP_TICKS_PER_SECOND * delay);
163 if (async == NULL) {
164 coap_pdu_set_code(response, COAP_RESPONSE_CODE_SERVICE_UNAVAILABLE);
165 return;
166 }
167 /*
168 * Not setting response code will cause empty ACK to be sent
169 * if Confirmable
170 */
171 return;
172 }
173 /* async is set up, so this is the delayed request */
174 /* remove any stored app data associated with 'async' here */
176 /* Send back the appropriate data */
178 coap_add_data_large_response(resource, session, request, response,
179 query, COAP_MEDIATYPE_TEXT_PLAIN, -1, 0, 4,
180 (const uint8_t *)"done", NULL, NULL);
181 coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTENT);
182 /* async is automatically removed by libcoap on return from this handler */
184 }
185
187 coap_handler(3)
188
190 See
191 "RFC7252: The Constrained Application Protocol (CoAP)"
193 for further information.
195
197 Please report bugs on the mailing list for libcoap:
198 libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
199 https://github.com/obgm/libcoap/issues
200
202 The libcoap project <libcoap-developers@lists.sourceforge.net>
203coap_async 4.3.4 10/09/2023 COAP_ASYNC(3)