'\" t
.\" Title: coap_context
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 10/28/2023
.\" Manual: libcoap Manual
.\" Source: coap_context 4.3.4
.\" Language: English
.\"
.TH "COAP_CONTEXT" "3" "10/28/2023" "coap_context 4\&.3\&.4" "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_context, coap_new_context, coap_free_context, coap_context_set_max_idle_sessions, coap_context_get_max_idle_sessions, coap_context_set_max_handshake_sessions, coap_context_get_max_handshake_sessions, coap_context_set_session_timeout, coap_context_get_session_timeout, coap_context_set_csm_timeout, coap_context_get_csm_timeout, coap_context_set_max_token_size \- Work with CoAP contexts
.SH "SYNOPSIS"
.sp
\fB#include \fR
.sp
\fBcoap_context_t *coap_new_context(const coap_address_t *\fR\fB\fIlisten_addr\fR\fR\fB);\fR
.sp
\fBvoid coap_free_context(coap_context_t *\fR\fB\fIcontext\fR\fR\fB);\fR
.sp
\fBvoid coap_context_set_max_idle_sessions(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, unsigned int \fR\fB\fImax_idle_sessions\fR\fR\fB);\fR
.sp
\fBunsigned int coap_context_get_max_idle_sessions( const coap_context_t *\fR\fB\fIcontext\fR\fR\fB);\fR
.sp
\fBvoid coap_context_set_max_handshake_sessions(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, unsigned int \fR\fB\fImax_handshake_sessions\fR\fR\fB);\fR
.sp
\fBunsigned int coap_context_get_max_handshake_sessions( const coap_context_t *\fR\fB\fIcontext\fR\fR\fB);\fR
.sp
\fBvoid coap_context_set_session_timeout(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, unsigned int \fR\fB\fIsession_timeout\fR\fR\fB);\fR
.sp
\fBunsigned int coap_context_get_session_timeout( const coap_context_t *\fR\fB\fIcontext\fR\fR\fB);\fR
.sp
\fBvoid coap_context_set_csm_timeout(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, unsigned int \fR\fB\fIcsm_timeout\fR\fR\fB);\fR
.sp
\fBunsigned int coap_context_get_csm_timeout(const coap_context_t *\fR\fB\fIcontext\fR\fR\fB);\fR
.sp
\fBvoid coap_context_set_max_token_size(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, size_t \fR\fB\fImax_token_size\fR\fR\fB);\fR
.sp
For specific (D)TLS library support, link with \fB\-lcoap\-3\-notls\fR, \fB\-lcoap\-3\-gnutls\fR, \fB\-lcoap\-3\-openssl\fR, \fB\-lcoap\-3\-mbedtls\fR or \fB\-lcoap\-3\-tinydtls\fR\&. Otherwise, link with \fB\-lcoap\-3\fR to get the default (D)TLS library support\&.
.SH "DESCRIPTION"
.sp
This man page focuses on the CoAP Context and how to update or get information from the opaque coap_context_t structure\&.
.sp
The CoAP stack\(cqs global state is stored in a coap_context_t Context object\&. Resources, Endpoints and Sessions are associated with this context object\&. There can be more than one coap_context_t object per application, it is up to the application to manage each one accordingly\&.
.SH "FUNCTIONS"
.sp
\fBFunction: coap_new_context()\fR
.sp
The \fBcoap_new_context\fR() function creates a new Context that is then used to keep all the CoAP Resources, Endpoints and Sessions information\&. The optional \fIlisten_addr\fR parameter, if set for a CoAP server, creates an Endpoint that is added to the \fIcontext\fR that is listening for un\-encrypted traffic on the IP address and port number defined by \fIlisten_addr\fR\&.
.sp
\fBFunction: coap_free_context()\fR
.sp
The \fBcoap_free_context\fR() function must be used to release the CoAP stack \fIcontext\fR\&. It clears all entries from the receive queue and send queue and deletes the Resources that have been registered with \fIcontext\fR, and frees the attached Sessions and Endpoints\&.
.sp
\fBWARNING:\fR It is unsafe to call \fBcoap_free_context\fR() in an atexit() handler as other libraries may also call atexit() and clear down some CoAP required functionality\&.
.sp
\fBFunction: coap_context_set_max_idle_sessions()\fR
.sp
The \fBcoap_context_set_max_idle_sessions\fR() function sets the maximum number of idle server sessions to \fImax_idle_sessions\fR for \fIcontext\fR\&. If this number is exceeded, the least recently used server session is completely removed\&. 0 (the initial default) means that the number of idle sessions is not monitored\&.
.sp
\fBFunction: coap_context_get_max_idle_sessions()\fR
.sp
The \fBcoap_context_get_max_idle_sessions\fR() function returns the maximum number of idle server sessions for \fIcontext\fR\&.
.sp
\fBFunction: coap_context_set_max_handshake_sessions()\fR
.sp
The \fBcoap_context_set_max_handshake_sessions\fR() function sets the maximum number of outstanding server sessions in (D)TLS handshake to \fImax_handshake_sessions\fR for \fIcontext\fR\&. If this number is exceeded, the least recently used server session in handshake is completely removed\&. 0 (the default) means that the number of handshakes is not monitored\&.
.sp
\fBFunction: coap_context_get_max_handshake_sessions()\fR
.sp
The \fBcoap_context_get_max_handshake_sessions\fR() function returns the maximum number of outstanding server sessions in (D)TLS handshake for \fIcontext\fR\&.
.sp
\fBFunction: coap_context_set_session_timeout()\fR
.sp
The \fBcoap_context_set_session_timeout\fR() function sets the number of seconds of inactivity to \fIsession_timeout\fR for \fIcontext\fR before an idle server session is removed\&. 0 (the default) means wait for the default of 300 seconds\&.
.sp
\fBFunction: coap_context_get_session_timeout()\fR
.sp
The \fBcoap_context_get_session_timeout\fR() function returns the seconds to wait before timing out an idle server session for \fIcontext\fR\&.
.sp
\fBFunction: coap_context_set_csm_timeout()\fR
.sp
The \fBcoap_context_set_csm_timeout\fR() function sets the number of seconds to wait for a (TCP) CSM negotiation response from the peer to \fIcsm_timeout\fR for \fIcontext\fR\&. 0 (the default) means wait forever\&.
.sp
\fBFunction: coap_context_get_csm_timeout()\fR
.sp
The \fBcoap_context_get_csm_timeout\fR() function returns the seconds to wait for a (TCP) CSM negotiation response from the peer for \fIcontext\fR,
.sp
\fBFunction: coap_context_set_max_token_size()\fR
.sp
The \fBcoap_context_set_max_token_size\fR() function sets the \fImax_token_size\fR for \fIcontext\fR\&. \fImax_token_size\fR must be greater than 8 to indicate support for RFC8974 up to \fImax_token_size\fR bytes, else 8 to disable RFC8974 (if previously set)\&.
.sp
\fBNOTE:\fR For the client, it will send an initial PDU to test the server supports the requested extended token size as per "RFC8794 Section 2\&.2\&.2"
.SH "RETURN VALUES"
.sp
\fBcoap_new_context\fR() returns a newly created context or NULL if there is a creation failure\&.
.sp
\fBcoap_context_get_max_idle_sessions\fR() returns the maximum number of idle server sessions\&.
.sp
\fBcoap_context_get_max_handshake_sessions\fR() returns the maximum number of outstanding server sessions in (D)TLS handshake\&.
.sp
\fBcoap_context_get_session_timeout\fR() returns the seconds to wait before timing out an idle server session\&.
.sp
\fBcoap_context_get_csm_timeout\fR() returns the seconds to wait for a (TCP) CSM negotiation response from the peer\&.
.SH "SEE ALSO"
.sp
\fBcoap_session\fR(3)
.SH "FURTHER INFORMATION"
.sp
See
.sp
"RFC7252: The Constrained Application Protocol (CoAP)"
.sp
"RFC8974: Extended Tokens and Stateless Clients in the Constrained Application Protocol (CoAP)"
.sp
for further information\&.
.SH "BUGS"
.sp
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
.SH "AUTHORS"
.sp
The libcoap project