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) or separate
39 (RFC7252 5.2.2).
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 the packet containing the status and any
47 data.
48 Usually responses are piggybacked, but this man page focuses on
50 separate (async) support.
51 The function coap_async_is_supported() is used to determine if there is
53 async support or not.
54 The coap_register_async() function is used to set up an asynchronous
56 delayed request for the request PDU associated with the session. The
57 application request handler will get called with a copy of request
58 after delay ticks which will then cause a response to be sent. If delay
59 is 0, then the application request handler will not get called until
60 coap_async_trigger() or coap_async_set_delay() is called.
61 The coap_async_trigger() function is used to expire the delay for the
63 async definition, so the application request handler is almost
64 immediately called.
65 The coap_async_set_delay() function is used to update the remaining
67 delay before the application request handler is called for the async
68 definition. If delay is set to 0, then the application request handler
69 will not get called.
70 An example of usage here is coap_register_async() sets delay to 0, and
72 then when the response is ready at an indeterminate point in the
73 future, coap_async_set_delay() is called setting delay to 1.
74 Alternatively, coap_async_trigger() can be called.
75 The coap_free_async() function is used to delete an async definition.
77 The coap_find_async() function is used to determine if there is an
79 async definition based on the session and token token.
80 The coap_async_set_app_data() function is used to add in user defined
82 app_data to the async definition. It is the responsibility of the
83 application to release this data if appropriate. This would usually be
84 done when the application request handler is called under async
85 control.
86 The coap_async_get_app_data() function is used to retrieve any defined
88 application data from the async definition.
89
91 coap_async_is_supported() returns 1 if support is available, 0
92 otherwise.
93 coap_register_async() and coap_find_async() return a pointer to an
95 async definition or NULL if there is an error.
96 coap_async_get_app_data() returns a pointer to the user defined data.
98
100 CoAP Server Non-Encrypted Setup
101 #include <coap3/coap.h>
103 /*
105 * This example is used to demonstrate how to set up and use a "separate"
106 * response (empty ACK followed by data response at a later stage).
107 */
108 static void
109 hnd_get_with_delay(coap_session_t *session,
110 coap_resource_t *resource,
111 coap_pdu_t *request,
112 coap_string_t *query,
113 coap_pdu_t *response) {
114 unsigned long delay = 5;
115 size_t size;
116 coap_async_t *async;
117 coap_bin_const_t token = coap_pdu_get_token(request);
118 /*
120 * See if this is the initial, or delayed request
121 */
122 async = coap_find_async(session, token);
124 if (!async) {
125 /* Set up an async request to trigger delay in the future */
126 if (query) {
127 const uint8_t *p = query->s;
128 delay = 0;
130 for (size = query->length; size; --size, ++p)
131 delay = delay * 10 + (*p - '0');
132 if (delay == 0) {
133 coap_log(LOG_INFO, "async: delay of 0 not supported\n");
134 coap_pdu_set_code(response, COAP_RESPONSE_CODE_BAD_REQUEST);
135 return;
136 }
137 }
138 async = coap_register_async(session,
139 request,
140 COAP_TICKS_PER_SECOND * delay);
141 if (async == NULL) {
142 coap_pdu_set_code(response, COAP_RESPONSE_CODE_SERVICE_UNAVAILABLE);
143 return;
144 }
145 /*
146 * Not setting response code will cause empty ACK to be sent
147 * if Confirmable
148 */
149 return;
150 }
151 /* async is set up, so this is the delayed request */
152 /* remove any stored app data associated with 'async' here */
154 /* Send back the appropriate data */
156 coap_add_data_large_response(resource, session, request, response,
157 query, COAP_MEDIATYPE_TEXT_PLAIN, -1, 0, 4,
158 (const uint8_t *)"done", NULL, NULL);
159 coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTENT);
160 /* async is automatically removed by libcoap on return from this handler */
162 }
163
165 coap_handler(3)
166
168 See
169 "RFC7252: The Constrained Application Protocol (CoAP)"
171 for further information.
173
175 Please report bugs on the mailing list for libcoap:
176 libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
177 https://github.com/obgm/libcoap/issues
178
180 The libcoap project <libcoap-developers@lists.sourceforge.net>
181coap_async 4.3.1 01/19/2023 COAP_ASYNC(3)