1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc,tw=0: 3 4coap_async(3) 5============= 6:doctype: manpage 7:man source: coap_async 8:man version: @PACKAGE_VERSION@ 9:man manual: libcoap Manual 10 11NAME 12---- 13coap_async, 14coap_async_is_supported, 15coap_register_async, 16coap_async_set_delay, 17coap_find_async, 18coap_free_async, 19coap_async_set_app_data, 20coap_async_get_app_data 21- Work with CoAP async support 22 23SYNOPSIS 24-------- 25*#include <coap@LIBCOAP_API_VERSION@/coap.h>* 26 27*int coap_async_is_supported(void);* 28 29*coap_async_t *coap_register_async(coap_session_t *_session_, 30const coap_pdu_t *_request_, coap_tick_t _delay_);* 31 32*void coap_async_set_delay(coap_async_t *_async_, coap_tick_t _delay_);* 33 34*void coap_free_async(coap_session_t *_session_, coap_async_t *_async_);* 35 36*coap_async_t *coap_find_async(coap_session_t *_session_, 37coap_bin_const_t _token_);* 38 39*void coap_async_set_app_data(coap_async_t *_async_, void *_app_data_);* 40 41*void *coap_async_get_app_data(const coap_async_t *_async_);* 42 43For specific (D)TLS library support, link with 44*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*, 45*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls* 46or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*. Otherwise, link with 47*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support. 48 49DESCRIPTION 50----------- 51CoAP server responses can be piggybacked (RFC7252 5.2.1) or separate 52(RFC7252 5.2.2). 53 54For piggybacked responses, the response packet contains both the status and 55any data. 56 57For separate responses, there is an initial empty ACK response (Confirmable 58only - to stop the client re-transmitting the request) followed at a later time 59by the packet containing the status and any data. 60 61Usually responses are piggybacked, but this man page focuses on separate 62(async) support. 63 64The function *coap_async_is_supported*() is used to determine if there is 65async support or not. 66 67The *coap_register_async*() function is used to set up an asynchronous delayed 68request for the _request_ PDU associated with the _session_. The 69application request handler will get called with a copy of _request_ after 70_delay_ ticks which will then cause a response to be sent. If _delay_ is 0, 71then the application request handler will not get called. 72 73The *coap_async_set_delay*() function is used to update the remaining _delay_ 74before the application request handler is called for the _async_ definition. If 75_delay_ is set to 0, then the application request handler will not get called. 76 77An example of usage here is *coap_register_async*() sets _delay_ to 0, and 78then when the response is ready at an indeterminate point in the future, 79*coap_async_set_delay*() is called setting _delay_ to 1. 80 81The *coap_free_async*() function is used to delete an _async_ definition. 82 83The *coap_find_async*() function is used to determine if there is an async 84definition based on the _session_ and token _token_. 85 86The *coap_async_set_app_data*() function is used to add in user defined 87_app_data_ to the _async_ definition. It is the responsibility of the 88application to release this data if appropriate. This would usually be done 89when the application request handler is called under 'async' control. 90 91The *coap_async_get_app_data*() function is used to retrieve any defined 92application data from the _async_ definition. 93 94RETURN VALUES 95------------- 96 97*coap_async_is_supported*() returns 1 if support is available, 0 otherwise. 98 99*coap_register_async*() and *coap_find_async*() return a pointer to an async 100definition or NULL if there is an error. 101 102*coap_async_get_app_data*() returns a pointer to the user defined data. 103 104EXAMPLES 105-------- 106*CoAP Server Non-Encrypted Setup* 107 108[source, c] 109---- 110#include <coap@LIBCOAP_API_VERSION@/coap.h> 111 112/* 113 * This example is used to demonstrate how to set up and use a "separate" 114 * response (empty ACK followed by data response at a later stage). 115 */ 116static void 117hnd_get_with_delay(coap_session_t *session, 118 coap_resource_t *resource, 119 coap_pdu_t *request, 120 coap_string_t *query, 121 coap_pdu_t *response) { 122 unsigned long delay = 5; 123 size_t size; 124 coap_async_t *async; 125 coap_bin_const_t token = coap_pdu_get_token(request); 126 127 /* 128 * See if this is the initial, or delayed request 129 */ 130 131 async = coap_find_async(session, token); 132 if (!async) { 133 /* Set up an async request to trigger delay in the future */ 134 if (query) { 135 const uint8_t *p = query->s; 136 137 delay = 0; 138 for (size = query->length; size; --size, ++p) 139 delay = delay * 10 + (*p - '0'); 140 if (delay == 0) { 141 coap_log(LOG_INFO, "async: delay of 0 not supported\n"); 142 coap_pdu_set_code(response, COAP_RESPONSE_CODE_BAD_REQUEST); 143 return; 144 } 145 } 146 async = coap_register_async(session, 147 request, 148 COAP_TICKS_PER_SECOND * delay); 149 if (async == NULL) { 150 coap_pdu_set_code(response, COAP_RESPONSE_CODE_SERVICE_UNAVAILABLE); 151 return; 152 } 153 /* 154 * Not setting response code will cause empty ACK to be sent 155 * if Confirmable 156 */ 157 return; 158 } 159 /* async is set up, so this is the delayed request */ 160 161 /* remove any stored app data associated with 'async' here */ 162 163 /* Send back the appropriate data */ 164 coap_add_data_large_response(resource, session, request, response, 165 query, COAP_MEDIATYPE_TEXT_PLAIN, -1, 0, 4, 166 (const uint8_t *)"done", NULL, NULL); 167 coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTENT); 168 169 /* async is automatically removed by libcoap on return from this handler */ 170} 171 172---- 173 174SEE ALSO 175-------- 176*coap_handler*(3) 177 178FURTHER INFORMATION 179------------------- 180See 181 182"RFC7252: The Constrained Application Protocol (CoAP)" 183 184for further information. 185 186BUGS 187---- 188Please report bugs on the mailing list for libcoap: 189libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at 190https://github.com/obgm/libcoap/issues 191 192AUTHORS 193------- 194The libcoap project <libcoap-developers@lists.sourceforge.net> 195