xref: /third_party/libcoap/man/coap_context.txt.in

// -*- mode:doc; -*-
// vim: set syntax=asciidoc tw=0

coap_context(3)
===============
:doctype: manpage
:man source:   coap_context
:man version:  @PACKAGE_VERSION@
:man manual:   libcoap Manual

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

SYNOPSIS
--------
*#include <coap@LIBCOAP_API_VERSION@/coap.h>*

*coap_context_t *coap_new_context(const coap_address_t *_listen_addr_);*

*void coap_free_context(coap_context_t *_context_);*

*void coap_context_set_max_idle_sessions(coap_context_t *_context_,
unsigned int _max_idle_sessions_);*

*unsigned int coap_context_get_max_idle_sessions(
const coap_context_t *_context_);*

*void coap_context_set_max_handshake_sessions(coap_context_t *_context_,
unsigned int _max_handshake_sessions_);*

*unsigned int coap_context_get_max_handshake_sessions(
const coap_context_t *_context_);*

*void coap_context_set_session_timeout(coap_context_t *_context_,
unsigned int _session_timeout_);*

*unsigned int coap_context_get_session_timeout(
const coap_context_t *_context_);*

*void coap_context_set_csm_timeout(coap_context_t *_context_,
unsigned int _csm_timeout_);*

*unsigned int coap_context_get_csm_timeout(const coap_context_t *_context_);*

*void coap_context_set_max_token_size(coap_context_t *_context_,
size_t _max_token_size_);*

For specific (D)TLS library support, link with
*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*,
*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls*
or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*.   Otherwise, link with
*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support.

DESCRIPTION
-----------
This man page focuses on the CoAP Context and how to update or get information
from the opaque coap_context_t structure.

The CoAP stack's 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.

FUNCTIONS
---------

*Function: coap_new_context()*

The *coap_new_context*() function creates a new Context that is then used
to keep all the CoAP Resources, Endpoints and Sessions information.
The optional _listen_addr_ parameter, if set for a CoAP server, creates an
Endpoint that is added to the _context_ that is listening for un-encrypted
traffic on the IP address and port number defined by _listen_addr_.

*Function: coap_free_context()*

The *coap_free_context*() function must be used to release the CoAP stack
_context_.  It clears all entries from the receive queue and send queue and
deletes the Resources that have been registered with _context_, and frees the
attached Sessions and Endpoints.

*WARNING:* It is unsafe to call *coap_free_context*() in an atexit() handler
as other libraries may also call atexit() and clear down some CoAP
required functionality.

*Function: coap_context_set_max_idle_sessions()*

The *coap_context_set_max_idle_sessions*() function sets the maximum number of
idle server sessions to _max_idle_sessions_ for _context_.  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.

*Function: coap_context_get_max_idle_sessions()*

The *coap_context_get_max_idle_sessions*() function returns the maximum number
of idle server sessions for _context_.

*Function: coap_context_set_max_handshake_sessions()*

The *coap_context_set_max_handshake_sessions*() function sets the maximum
number of outstanding server sessions in (D)TLS handshake to
_max_handshake_sessions_ for _context_.  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.

*Function: coap_context_get_max_handshake_sessions()*

The *coap_context_get_max_handshake_sessions*() function returns the maximum
number of outstanding server sessions in (D)TLS handshake for _context_.

*Function: coap_context_set_session_timeout()*

The *coap_context_set_session_timeout*() function sets the number of seconds of
inactivity to _session_timeout_ for _context_ before an idle server session is
removed. 0 (the default) means wait for the default of 300 seconds.

*Function: coap_context_get_session_timeout()*

The *coap_context_get_session_timeout*() function returns the seconds to wait
before timing out an idle server session for _context_.

*Function: coap_context_set_csm_timeout()*

The *coap_context_set_csm_timeout*() function sets the number of seconds to
wait for a (TCP) CSM negotiation response from the peer to _csm_timeout_ for
_context_.  0 (the default) means wait forever.

*Function: coap_context_get_csm_timeout()*

The *coap_context_get_csm_timeout*() function returns the seconds to wait for
a (TCP) CSM negotiation response from the peer for _context_,

*Function: coap_context_set_max_token_size()*

The *coap_context_set_max_token_size*() function sets the _max_token_size_
for _context_.  _max_token_size_ must be greater than 8 to indicate
support for https://rfc-editor.org/rfc/rfc8974[RFC8974] up to _max_token_size_
bytes, else 8 to disable https://rfc-editor.org/rfc/rfc8974[RFC8974]
(if previously set).

*NOTE:* For the client, it will send an initial PDU to test the server
supports the requested extended token size as per
"https://rfc-editor.org/rfc/rfc8974.html#section-2.2.2[RFC8794 Section 2.2.2]"

RETURN VALUES
-------------
*coap_new_context*() returns a newly created context or
NULL if there is a creation failure.

*coap_context_get_max_idle_sessions*() returns the maximum number of idle
server sessions.

*coap_context_get_max_handshake_sessions*() returns the maximum number of
outstanding server sessions in (D)TLS handshake.

*coap_context_get_session_timeout*() returns the seconds to wait before timing
out an idle server session.

*coap_context_get_csm_timeout*() returns the seconds to wait for a (TCP) CSM
negotiation response from the peer.

SEE ALSO
--------
*coap_session*(3)

FURTHER INFORMATION
-------------------
See

"https://rfc-editor.org/rfc/rfc7252[RFC7252: The Constrained Application Protocol (CoAP)]"

"https://rfc-editor.org/rfc/rfc8974[RFC8974: Extended Tokens and Stateless Clients in the Constrained Application Protocol (CoAP)]"

for further information.

BUGS
----
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

AUTHORS
-------
The libcoap project <libcoap-developers@lists.sourceforge.net>