'\" t
.\"     Title: coap_keepalive
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 05/14/2022
.\"    Manual: libcoap Manual
.\"    Source: coap_keepalive 4.2.1
.\"  Language: English
.\"
.TH "COAP_KEEPALIVE" "3" "05/14/2022" "coap_keepalive 4\&.2\&.1" "libcoap Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
coap_keepalive, coap_context_set_keepalive \- work with CoAP keepalive
.SH "SYNOPSIS"
.sp
\fB#include <coap2/coap\&.h>\fR
.sp
\fBvoid void coap_context_set_keepalive(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, unsigned int \fR\fB\fIseconds\fR\fR\fB);\fR
.sp
Link with \fB\-lcoap\-2\fR, \fB\-lcoap\-2\-gnutls\fR, \fB\-lcoap\-2\-openssl\fR or \fB\-lcoap\-2\-tinydtls\fR depending on your (D)TLS library type\&.
.SH "DESCRIPTION"
.sp
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"\&.
.sp
For DTLS, this is done with the confirmable CoAP (0\&.00) Ping packet, which solicits a CoAP RST response\&. For TLS, this is done with Coap (7\&.02) Ping packet, which solicits a CoAP (7\&.03) Pong response, all handled by libcoap\&.
.sp
The \fBcoap_context_set_keepalive\fR() function needs to be called to update the \fIcontext\fR with the keepalive for idle traffic timeout of \fIseconds\fR\&. If \fIseconds\fR is set to 0, then the sending of keepalives is disabled\&. Any sessions created from this \fIcontext\fR will use the same \fIseconds\fR value to determine whether a keepalive "ping" is to be sent out or not\&.
.sp
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()\&.
.sp
If the keepalive fails to solicit a response, then this can be tracked by defining the handler to use by using coap_register_nack_handler() which will be called with a reason of COAP_NACK_TOO_MANY_RETRIES\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
\fBcoap_context_set_keepalive\fR() is supported by both the CoAP client and CoAP server\&.
.sp .5v
.RE
.SH "SEE ALSO"
.sp
\fBcoap_handler\fR(3)
.SH "FURTHER INFORMATION"
.sp
"RFC7252: The Constrained Application Protocol (CoAP)"
.sp
"RFC8323: CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets"
.SH "BUGS"
.sp
Please report bugs on the mailing list for libcoap: libcoap\-developers@lists\&.sourceforge\&.net
.SH "AUTHORS"
.sp
The libcoap project <libcoap\-developers@lists\&.sourceforge\&.net>