1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc,tw=0: 3 4coap_keepalive(3) 5================= 6:doctype: manpage 7:man source: coap_keepalive 8:man version: @PACKAGE_VERSION@ 9:man manual: libcoap Manual 10 11NAME 12---- 13coap_keepalive, 14coap_context_set_keepalive 15- Work with CoAP keepalive 16 17SYNOPSIS 18-------- 19*#include <coap@LIBCOAP_API_VERSION@/coap.h>* 20 21*void coap_context_set_keepalive(coap_context_t *_context_, 22unsigned int _seconds_);* 23 24For specific (D)TLS library support, link with 25*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*, 26*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls* 27or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*. Otherwise, link with 28*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support. 29 30DESCRIPTION 31----------- 32There may be a requirement to send out keepalive traffic when the CoAP session 33is idle (no packets have been sent or received for a specified period) to keep, 34say, an interim NAT device "warm" with the NAT translation state, or to 35periodically check whether the device at the other end of the session 36has "gone away". 37 38For UDP/DTLS, this is done with the confirmable CoAP (0.00) Ping packet, which 39solicits a CoAP RST response. For TCP/TLS, this is done with CoAP (7.02) Ping 40packet, which solicits a CoAP (7.03) Pong response, all handled by libcoap. 41 42The *coap_context_set_keepalive*() function needs to be called to update the 43_context_ with the keepalive for idle traffic timeout of _seconds_. If 44_seconds_ is set to 0 (the default), then the sending of keepalives is 45disabled. Any sessions created from this _context_ will use the same 46_seconds_ value to determine whether a keepalive "ping" is to be sent out or 47not. 48 49Applications can track the usage of the receipt of "pings" and receipt of 50"responses" by defining the respective handlers to use by using 51*coap_register_ping_handler*() and *coap_register_pong_handler*(). 52 53If the keepalive fails to solicit a response, then this can be tracked by 54defining the handler to use by using *coap_register_nack_handler*() which will 55be called with a reason of COAP_NACK_TOO_MANY_RETRIES. 56 57*NOTE:* *coap_context_set_keepalive*() is supported by both the CoAP client and 58CoAP server. 59 60SEE ALSO 61-------- 62*coap_handler*(3) 63 64FURTHER INFORMATION 65------------------- 66"RFC7252: The Constrained Application Protocol (CoAP)" 67 68"RFC8323: CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets" 69 70BUGS 71---- 72Please report bugs on the mailing list for libcoap: 73libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at 74https://github.com/obgm/libcoap/issues 75 76AUTHORS 77------- 78The libcoap project <libcoap-developers@lists.sourceforge.net> 79