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_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

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_set_delay(coap_async_t *async, coap_tick_t delay);
20
21       void coap_free_async(coap_session_t *session, coap_async_t *async);
22
23       coap_async_t *coap_find_async(coap_session_t *session, coap_bin_const_t
24       token);
25
26       void coap_async_set_app_data(coap_async_t *async, void *app_data);
27
28       void *coap_async_get_app_data(const coap_async_t *async);
29
30       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

DESCRIPTION

36       CoAP server responses can be piggybacked (RFC7252 5.2.1) or separate
37       (RFC7252 5.2.2).
38
39       For piggybacked responses, the response packet contains both the status
40       and any data.
41
42       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
47       Usually responses are piggybacked, but this man page focuses on
48       separate (async) support.
49
50       The function coap_async_is_supported() is used to determine if there is
51       async support or not.
52
53       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
59       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
64       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
68       The coap_free_async() function is used to delete an async definition.
69
70       The coap_find_async() function is used to determine if there is an
71       async definition based on the session and token token.
72
73       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
79       The coap_async_get_app_data() function is used to retrieve any defined
80       application data from the async definition.
81

RETURN VALUES

83       coap_async_is_supported() returns 1 if support is available, 0
84       otherwise.
85
86       coap_register_async() and coap_find_async() return a pointer to an
87       async definition or NULL if there is an error.
88
89       coap_async_get_app_data() returns a pointer to the user defined data.
90

EXAMPLES

92       CoAP Server Non-Encrypted Setup
93
94           #include <coap3/coap.h>
95
96           /*
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
111             /*
112              * See if this is the initial, or delayed request
113              */
114
115             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
121                 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
145             /* remove any stored app data associated with 'async' here */
146
147             /* 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
153             /* async is automatically removed by libcoap on return from this handler */
154           }
155

SEE ALSO

157       coap_handler(3)
158

FURTHER INFORMATION

160       See
161
162       "RFC7252: The Constrained Application Protocol (CoAP)"
163
164       for further information.
165

BUGS

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

AUTHORS

172       The libcoap project <libcoap-developers@lists.sourceforge.net>
173
174
175
176coap_async 4.3.0                  01/20/2022                     COAP_ASYNC(3)
Impressum