1COAP_ASYNC(3) libcoap Manual COAP_ASYNC(3)
2
6 coap_async, coap_async_is_supported, coap_register_async,
7 coap_async_set_delay, coap_find_async, coap_free_async,
8 coap_async_set_app_data, coap_async_get_app_data - Work with CoAP async
9 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_set_delay(coap_async_t *async, coap_tick_t delay);
20 void coap_free_async(coap_session_t *session, coap_async_t *async);
22 coap_async_t *coap_find_async(coap_session_t *session, coap_bin_const_t
24 token);
25 void coap_async_set_app_data(coap_async_t *async, void *app_data);
27 void *coap_async_get_app_data(const coap_async_t *async);
29 For specific (D)TLS library support, link with -lcoap-3-notls,
31 -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or
32 -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default
33 (D)TLS library support.
34
36 CoAP server responses can be piggybacked (RFC7252 5.2.1) or separate
37 (RFC7252 5.2.2).
38 For piggybacked responses, the response packet contains both the status
40 and any data.
41 For separate responses, there is an initial empty ACK response
43 (Confirmable only - to stop the client re-transmitting the request)
44 followed at a later time by the packet containing the status and any
45 data.
46 Usually responses are piggybacked, but this man page focuses on
48 separate (async) support.
49 The function coap_async_is_supported() is used to determine if there is
51 async support or not.
52 The coap_register_async() function is used to set up an asynchronous
54 delayed request for the request PDU associated with the session. The
55 application request handler will get called with a copy of request
56 after delay ticks which will then cause a response to be sent. If delay
57 is 0, then the application request handler will not get called.
58 The coap_async_set_delay() function is used to update the remaining
60 delay before the application request handler is called for the async
61 definition. If delay is set to 0, then the application request handler
62 will not get called.
63 An example of usage here is coap_register_async() sets delay to 0, and
65 then when the response is ready at an indeterminate point in the
66 future, coap_async_set_delay() is called setting delay to 1.
67 The coap_free_async() function is used to delete an async definition.
69 The coap_find_async() function is used to determine if there is an
71 async definition based on the session and token token.
72 The coap_async_set_app_data() function is used to add in user defined
74 app_data to the async definition. It is the responsibility of the
75 application to release this data if appropriate. This would usually be
76 done when the application request handler is called under async
77 control.
78 The coap_async_get_app_data() function is used to retrieve any defined
80 application data from the async definition.
81
83 coap_async_is_supported() returns 1 if support is available, 0
84 otherwise.
85 coap_register_async() and coap_find_async() return a pointer to an
87 async definition or NULL if there is an error.
88 coap_async_get_app_data() returns a pointer to the user defined data.
90
92 CoAP Server Non-Encrypted Setup
93 #include <coap3/coap.h>
95 /*
97 * This example is used to demonstrate how to set up and use a "separate"
98 * response (empty ACK followed by data response at a later stage).
99 */
100 static void
101 hnd_get_with_delay(coap_session_t *session,
102 coap_resource_t *resource,
103 coap_pdu_t *request,
104 coap_string_t *query,
105 coap_pdu_t *response) {
106 unsigned long delay = 5;
107 size_t size;
108 coap_async_t *async;
109 coap_bin_const_t token = coap_pdu_get_token(request);
110 /*
112 * See if this is the initial, or delayed request
113 */
114 async = coap_find_async(session, token);
116 if (!async) {
117 /* Set up an async request to trigger delay in the future */
118 if (query) {
119 const uint8_t *p = query->s;
120 delay = 0;
122 for (size = query->length; size; --size, ++p)
123 delay = delay * 10 + (*p - '0');
124 if (delay == 0) {
125 coap_log(LOG_INFO, "async: delay of 0 not supported\n");
126 coap_pdu_set_code(response, COAP_RESPONSE_CODE_BAD_REQUEST);
127 return;
128 }
129 }
130 async = coap_register_async(session,
131 request,
132 COAP_TICKS_PER_SECOND * delay);
133 if (async == NULL) {
134 coap_pdu_set_code(response, COAP_RESPONSE_CODE_SERVICE_UNAVAILABLE);
135 return;
136 }
137 /*
138 * Not setting response code will cause empty ACK to be sent
139 * if Confirmable
140 */
141 return;
142 }
143 /* async is set up, so this is the delayed request */
144 /* remove any stored app data associated with 'async' here */
146 /* Send back the appropriate data */
148 coap_add_data_large_response(resource, session, request, response,
149 query, COAP_MEDIATYPE_TEXT_PLAIN, -1, 0, 4,
150 (const uint8_t *)"done", NULL, NULL);
151 coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTENT);
152 /* async is automatically removed by libcoap on return from this handler */
154 }
155
157 coap_handler(3)
158
160 See
161 "RFC7252: The Constrained Application Protocol (CoAP)"
163 for further information.
165
167 Please report bugs on the mailing list for libcoap:
168 libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
169 https://github.com/obgm/libcoap/issues
170
172 The libcoap project <libcoap-developers@lists.sourceforge.net>
173coap_async 4.3.0 01/20/2022 COAP_ASYNC(3)