NAME

       coap_async, coap_async_is_supported, coap_register_async, coap_async_trigger,
       coap_async_set_delay, coap_find_async, coap_free_async, coap_async_set_app_data,
       coap_async_get_app_data - Work with CoAP async support

SYNOPSIS

       #include <coap3/coap.h>

       int coap_async_is_supported(void);

       coap_async_t *coap_register_async(coap_session_t *session, const coap_pdu_t *request,
       coap_tick_t delay);

       void coap_async_trigger(coap_async_t *async);

       void coap_async_set_delay(coap_async_t *async, coap_tick_t delay);

       void coap_free_async(coap_session_t *session, coap_async_t *async);

       coap_async_t *coap_find_async(coap_session_t *session, coap_bin_const_t token);

       void coap_async_set_app_data(coap_async_t *async, void *app_data);

       void *coap_async_get_app_data(const coap_async_t *async);

       For specific (D)TLS library support, link with -lcoap-3-notls, -lcoap-3-gnutls,
       -lcoap-3-openssl, -lcoap-3-mbedtls or -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to
       get the default (D)TLS library support.

DESCRIPTION

       CoAP server responses can be piggybacked ("RFC7252 5.2.1. Piggybacked") or separate
       ("RFC7252 5.2.2. Separate").

       For piggybacked responses, the response packet contains both the status and any data.

       For separate responses, there is an initial empty ACK response (Confirmable only - to stop
       the client re-transmitting the request) followed at a later time by a packet containing
       the status and any data.

       Usually responses are piggybacked, but this man page focuses on a mechanism for providing
       separate (async) support.

       NOTE: If a server is providing Proxy support, then the server code should return from the
       request handler with no response code set (i.e. respond with empty ACK) and then send back
       the response as provided by the upstream server when received, so no need to use the async
       support.

FUNCTIONS

       Function: coap_async_is_supported()

       The coap_async_is_supported() function is used to determine if there is async support or
       not compiled into libcoap.

       Function: coap_register_async()

       The coap_register_async() function is used to set up an asynchronous delayed request for
       the request PDU associated with the session. The application request handler will get
       called with a copy of request after delay ticks which will then cause a response to be
       sent. If delay is 0, then the application request handler will not get called until
       coap_async_trigger() or coap_async_set_delay() is called.

       Function: coap_async_trigger()

       The coap_async_trigger() function is used to expire the delay for the async definition, so
       the application request handler is almost immediately called.

       Function: coap_async_set_delay()

       The coap_async_set_delay() function is used to update the remaining delay before the
       application request handler is called for the async definition. If delay is set to 0, then
       the application request handler will not get called.

       An example of usage here is coap_register_async() sets delay to 0, and then when the
       response is ready at an indeterminate point in the future, coap_async_set_delay() is
       called setting delay to 1. Alternatively, coap_async_trigger() can be called.

       Function: coap_free_async()

       The coap_free_async() function is used to delete an async definition.

       Function: coap_find_async()

       The coap_find_async() function is used to determine if there is an async definition based
       on the session and token token.

       Function: coap_async_set_app_data()

       The coap_async_set_app_data() function is used to add in user defined app_data to the
       async definition. It is the responsibility of the application to release this data if
       appropriate. This would usually be done when the application request handler is called
       under async control.

       Function: coap_async_get_app_data()

       The coap_async_get_app_data() function is used to retrieve any defined application data
       from the async definition.

RETURN VALUES

       coap_async_is_supported() returns 1 if support is available, 0 otherwise.

       coap_register_async() and coap_find_async() return a pointer to an async definition or
       NULL if there is an error.

       coap_async_get_app_data() returns a pointer to the user defined data.

EXAMPLES

       CoAP Server Non-Encrypted Setup

           #include <coap3/coap.h>

           /*
            * This example is used to demonstrate how to set up and use a "separate"
            * response (empty ACK followed by data response at a later stage).
            */
           static void
           hnd_get_with_delay(coap_session_t *session,
                         coap_resource_t *resource,
                         coap_pdu_t *request,
                         coap_string_t *query,
                         coap_pdu_t *response) {
             unsigned long delay = 5;
             size_t size;
             coap_async_t *async;
             coap_bin_const_t token = coap_pdu_get_token(request);

             /*
              * See if this is the initial, or delayed request
              */

             async = coap_find_async(session, token);
             if (!async) {
               /* Set up an async request to trigger delay in the future */
               if (query) {
                 const uint8_t *p = query->s;

                 delay = 0;
                 for (size = query->length; size; --size, ++p)
                   delay = delay * 10 + (*p - '0');
                 if (delay == 0) {
                   coap_log_info("async: delay of 0 not supported\n");
                   coap_pdu_set_code(response, COAP_RESPONSE_CODE_BAD_REQUEST);
                   return;
                 }
               }
               async = coap_register_async(session,
                                           request,
                                           COAP_TICKS_PER_SECOND * delay);
               if (async == NULL) {
                 coap_pdu_set_code(response, COAP_RESPONSE_CODE_SERVICE_UNAVAILABLE);
                 return;
               }
               /*
                * Not setting response code will cause empty ACK to be sent
                * if Confirmable
                */
               return;
             }
             /* async is set up, so this is the delayed request */

             /* remove any stored app data associated with 'async' here */

             /* Send back the appropriate data */
             coap_add_data_large_response(resource, session, request, response,
                                          query, COAP_MEDIATYPE_TEXT_PLAIN, -1, 0, 4,
                                          (const uint8_t *)"done", NULL, NULL);
             coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTENT);

             /* async is automatically removed by libcoap on return from this handler */
           }

SEE ALSO

       coap_handler(3)

FURTHER INFORMATION

       See

       "RFC7252: The Constrained Application Protocol (CoAP)"

       for further information.

BUGS

       Please report bugs on the mailing list for libcoap:
       libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
       https://github.com/obgm/libcoap/issues

AUTHORS

       The libcoap project <libcoap-developers@lists.sourceforge.net>