1COAP_ASYNC(3)                   libcoap Manual                   COAP_ASYNC(3)
2
3
4

NAME

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

SYNOPSIS

12       #include <coap3/coap.h>
13
14       int coap_async_is_supported(void);
15
16       coap_async_t *coap_register_async(coap_session_t *session, const
17       coap_pdu_t *request, coap_tick_t delay);
18
19       void coap_async_trigger(coap_async_t *async);
20
21       void coap_async_set_delay(coap_async_t *async, coap_tick_t delay);
22
23       void coap_free_async(coap_session_t *session, coap_async_t *async);
24
25       coap_async_t *coap_find_async(coap_session_t *session, coap_bin_const_t
26       token);
27
28       void coap_async_set_app_data(coap_async_t *async, void *app_data);
29
30       void *coap_async_get_app_data(const coap_async_t *async);
31
32       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

DESCRIPTION

38       CoAP server responses can be piggybacked (RFC7252 5.2.1) or separate
39       (RFC7252 5.2.2).
40
41       For piggybacked responses, the response packet contains both the status
42       and any data.
43
44       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
49       Usually responses are piggybacked, but this man page focuses on
50       separate (async) support.
51
52       The function coap_async_is_supported() is used to determine if there is
53       async support or not.
54
55       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
62       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
66       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
71       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
76       The coap_free_async() function is used to delete an async definition.
77
78       The coap_find_async() function is used to determine if there is an
79       async definition based on the session and token token.
80
81       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
87       The coap_async_get_app_data() function is used to retrieve any defined
88       application data from the async definition.
89

RETURN VALUES

91       coap_async_is_supported() returns 1 if support is available, 0
92       otherwise.
93
94       coap_register_async() and coap_find_async() return a pointer to an
95       async definition or NULL if there is an error.
96
97       coap_async_get_app_data() returns a pointer to the user defined data.
98

EXAMPLES

100       CoAP Server Non-Encrypted Setup
101
102           #include <coap3/coap.h>
103
104           /*
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
119             /*
120              * See if this is the initial, or delayed request
121              */
122
123             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
129                 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
153             /* remove any stored app data associated with 'async' here */
154
155             /* 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
161             /* async is automatically removed by libcoap on return from this handler */
162           }
163

SEE ALSO

165       coap_handler(3)
166

FURTHER INFORMATION

168       See
169
170       "RFC7252: The Constrained Application Protocol (CoAP)"
171
172       for further information.
173

BUGS

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

AUTHORS

180       The libcoap project <libcoap-developers@lists.sourceforge.net>
181
182
183
184coap_async 4.3.1                  01/19/2023                     COAP_ASYNC(3)
Impressum