oracular (3) coap_keepalive.3.gz

NAME

       coap_keepalive, coap_context_set_keepalive - Work with CoAP keepalive

SYNOPSIS

       #include <coap3/coap.h>

       void coap_context_set_keepalive(coap_context_t *context, unsigned int seconds);

       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

       There may be a requirement to send out keepalive traffic when the CoAP session is idle (no packets have
       been sent or received for a specified period) to keep, say, an interim NAT device "warm" with the NAT
       translation state, or to periodically check whether the device at the other end of the session has "gone
       away".

       For UDP/DTLS, this is done with the confirmable CoAP (0.00) Ping packet, which solicits a CoAP RST
       response. For TCP/TLS, this is done with CoAP (7.02) Ping packet, which solicits a CoAP (7.03) Pong
       response, all handled by libcoap.

FUNCTIONS

       Function: coap_context_set_keepalive()

       The coap_context_set_keepalive() function needs to be called to update the context with the keepalive for
       idle traffic timeout of seconds. If seconds is set to 0 (the default), then the sending of keepalives is
       disabled. Any sessions created from this context will use the same seconds value to determine whether a
       keepalive "ping" is to be sent out or not.

       Applications can track the usage of the receipt of "pings" and receipt of "responses" by defining the
       respective handlers to use by using coap_register_ping_handler() and coap_register_pong_handler().

       If the keepalive fails to solicit a response, then this can be tracked by defining the handler to use by
       using coap_register_event_handler() which will be called with a reason of COAP_EVENT_KEEPALIVE_FAILURE.

       NOTE: As this may be used to keep an interim NAT device "warm", the exponentially increasing retransmit
       times for CON requests is limited to seconds, but the retransmit counter is not affected. Unless needed,
       seconds shold not be set to less than 30.

SEE ALSO

       coap_handler(3)

FURTHER INFORMATION

       See

       "RFC7252: The Constrained Application Protocol (CoAP)"

       "RFC8323: CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets"

       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>