From a5c0d12354ed00a755364d7b0a03b93eecf2d4a8 Mon Sep 17 00:00:00 2001 From: Jon Shallow Date: Wed, 4 Aug 2021 14:14:37 +0100 Subject: [PATCH] doc: Document the coap_can_exit() function --- include/coap3/net.h | 9 ++++++++- man/coap_io.txt.in | 14 ++++++++++++++ 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/include/coap3/net.h b/include/coap3/net.h index 577a0b5d5a..25cc1a0ee9 100644 --- a/include/coap3/net.h +++ b/include/coap3/net.h @@ -483,7 +483,14 @@ int coap_handle_event(coap_context_t *context, coap_session_t *session); /** * Returns 1 if there are no messages to send or to dispatch in the context's - * queues. */ + * queues. + * + * @param context The CoAP context to check. + * + * @return @c 0 if there are still pending transmits else @c 1 if nothing + * queued for transmission. Note that @c 0 does not mean there has + * been a response to a transmitted request. + */ int coap_can_exit(coap_context_t *context); /** diff --git a/man/coap_io.txt.in b/man/coap_io.txt.in index 9911c6305d..ed379a4f24 100644 --- a/man/coap_io.txt.in +++ b/man/coap_io.txt.in @@ -44,6 +44,8 @@ coap_tick_t _now_)*; *void coap_io_do_epoll(coap_context_t *_context_, struct epoll_event *_events_, size_t _nevents_)*; +*int coap_can_exit(coap_context_t *_context_)*; + For specific (D)TLS library support, link with *-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*, *-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls* @@ -73,6 +75,10 @@ processing. If _timeout_ms_ is set to COAP_IO_NO_WAIT, then *coap_io_process*() will return immediately after processing without waiting for any new input packets to arrive. +*NOTE:* *coap_io_process*() should not be called from within a callback +handler as defined using the coap_register_*_handler() as *coap_io_process*() +will likely recursively call the same handler. + There are two methods of how to call *coap_io_process*(). 1. Have *coap_io_process*() called from within a while() loop. Under idle @@ -161,6 +167,11 @@ as an event returned from a *epoll_wait*() call. This file descriptor will get updated with information (read, write etc. available) whenever any of the internal to libcoap file descriptors (sockets) change state. +The *coap_can_exit*() function checks to see if there are any outstanding +PDUs to transmit associated with _context_ and returns 1 if there is nothing +outstanding else 0. This function does not check that all requests transmitted +have been responded to. + RETURN VALUES ------------- *coap_io_process*() and *coap_io_process_with_fds*() returns the time, in @@ -173,6 +184,9 @@ descriptor to monitor, or -1 if epoll is not configured in libcoap. *coap_io_prepare_io*() and *coap_io_prepare_epoll*() returns the number of milli-seconds that need to be waited before the function should next be called. +*coap_can_exit*() returns 1 if there is nothing outstanding to transmit else +returns 0. + EXAMPLES -------- *Method One - use coap_io_process()*