coap_context_set_keepalive(3)

1COAP_KEEPALIVE(3)               libcoap Manual               COAP_KEEPALIVE(3)
2
3
4

NAME

6       coap_keepalive, coap_context_set_keepalive - Work with CoAP keepalive
7

SYNOPSIS

9       #include <coap3/coap.h>
10
11       void coap_context_set_keepalive(coap_context_t *context, unsigned int
12       seconds);
13
14       For specific (D)TLS library support, link with -lcoap-3-notls,
15       -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or
16       -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default
17       (D)TLS library support.
18

DESCRIPTION

20       There may be a requirement to send out keepalive traffic when the CoAP
21       session is idle (no packets have been sent or received for a specified
22       period) to keep, say, an interim NAT device "warm" with the NAT
23       translation state, or to periodically check whether the device at the
24       other end of the session has "gone away".
25
26       For UDP/DTLS, this is done with the confirmable CoAP (0.00) Ping
27       packet, which solicits a CoAP RST response. For TCP/TLS, this is done
28       with CoAP (7.02) Ping packet, which solicits a CoAP (7.03) Pong
29       response, all handled by libcoap.
30

FUNCTIONS

32       Function: coap_context_set_keepalive()
33
34       The coap_context_set_keepalive() function needs to be called to update
35       the context with the keepalive for idle traffic timeout of seconds. If
36       seconds is set to 0 (the default), then the sending of keepalives is
37       disabled. Any sessions created from this context will use the same
38       seconds value to determine whether a keepalive "ping" is to be sent out
39       or not.
40
41       Applications can track the usage of the receipt of "pings" and receipt
42       of "responses" by defining the respective handlers to use by using
43       coap_register_ping_handler() and coap_register_pong_handler().
44
45       If the keepalive fails to solicit a response, then this can be tracked
46       by defining the handler to use by using coap_register_event_handler()
47       which will be called with a reason of COAP_EVENT_KEEPALIVE_FAILURE.
48
49       NOTE: As this may be used to keep an interim NAT device "warm", the
50       exponentially increasing retransmit times for CON requests is limited
51       to seconds, but the retransmit counter is not affected. Unless needed,
52       seconds shold not be set to less than 30.
53

FURTHER INFORMATION

58       See
59
60       "RFC7252: The Constrained Application Protocol (CoAP)"
61
62       "RFC8323: CoAP (Constrained Application Protocol) over TCP, TLS, and
63       WebSockets"
64
65       for further information.
66

BUGS

68       Please report bugs on the mailing list for libcoap:
69       libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
70       https://github.com/obgm/libcoap/issues
71

AUTHORS

73       The libcoap project <libcoap-developers@lists.sourceforge.net>
74
75
76
77coap_keepalive 4.3.4              10/09/2023                 COAP_KEEPALIVE(3)