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
42FUNCTIONS
43---------
44
45*Function: coap_context_set_keepalive()*
46
47The *coap_context_set_keepalive*() function needs to be called to update the
48_context_ with the keepalive for idle traffic timeout of _seconds_.  If
49_seconds_ is set to 0 (the default), then the sending of keepalives is
50disabled.  Any sessions created from this _context_ will use the same
51_seconds_ value to determine whether a keepalive "ping" is to be sent out or
52not.
53
54Applications can track the usage of the receipt of "pings" and receipt of
55"responses" by defining the respective handlers to use by using
56*coap_register_ping_handler*() and *coap_register_pong_handler*().
57
58If the keepalive fails to solicit a response, then this can be tracked by
59defining the handler to use by using *coap_register_event_handler*() which will
60be called with a reason of COAP_EVENT_KEEPALIVE_FAILURE.
61
62*NOTE:* As this may be used to keep an interim NAT device "warm", the
63exponentially increasing retransmit times for CON requests is limited to
64_seconds_, but the retransmit counter is not affected. Unless needed,
65_seconds_ shold not be set to less than 30.
66
67SEE ALSO
68--------
69*coap_handler*(3)
70
71FURTHER INFORMATION
72-------------------
73See
74
75"https://rfc-editor.org/rfc/rfc7252[RFC7252: The Constrained Application Protocol (CoAP)]"
76
77"https://rfc-editor.org/rfc/rfc8323[RFC8323: CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets]"
78
79for further information.
80
81BUGS
82----
83Please report bugs on the mailing list for libcoap:
84libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
85https://github.com/obgm/libcoap/issues
86
87AUTHORS
88-------
89The libcoap project <libcoap-developers@lists.sourceforge.net>
90