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 <coap3/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-3-notls, -lcoap-3-gnutls,
       -lcoap-3-openssl, -lcoap-3-mbedtls or -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 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 RFC8974 up to max_token_size
       bytes, else 8 to disable 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 "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

       "RFC7252: The Constrained Application Protocol (CoAP)"

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