// -*- 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_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