1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc tw=0 3 4coap_context(3) 5=============== 6:doctype: manpage 7:man source: coap_context 8:man version: @PACKAGE_VERSION@ 9:man manual: libcoap Manual 10 11NAME 12---- 13coap_context, 14coap_new_context, 15coap_free_context, 16coap_context_set_max_idle_sessions, 17coap_context_get_max_idle_sessions, 18coap_context_set_max_handshake_sessions, 19coap_context_get_max_handshake_sessions, 20coap_context_set_session_timeout, 21coap_context_get_session_timeout, 22coap_context_set_csm_timeout, 23coap_context_get_csm_timeout, 24coap_context_set_max_token_size 25- Work with CoAP contexts 26 27SYNOPSIS 28-------- 29*#include <coap@LIBCOAP_API_VERSION@/coap.h>* 30 31*coap_context_t *coap_new_context(const coap_address_t *_listen_addr_);* 32 33*void coap_free_context(coap_context_t *_context_);* 34 35*void coap_context_set_max_idle_sessions(coap_context_t *_context_, 36unsigned int _max_idle_sessions_);* 37 38*unsigned int coap_context_get_max_idle_sessions( 39const coap_context_t *_context_);* 40 41*void coap_context_set_max_handshake_sessions(coap_context_t *_context_, 42unsigned int _max_handshake_sessions_);* 43 44*unsigned int coap_context_get_max_handshake_sessions( 45const coap_context_t *_context_);* 46 47*void coap_context_set_session_timeout(coap_context_t *_context_, 48unsigned int _session_timeout_);* 49 50*unsigned int coap_context_get_session_timeout( 51const coap_context_t *_context_);* 52 53*void coap_context_set_csm_timeout(coap_context_t *_context_, 54unsigned int _csm_timeout_);* 55 56*unsigned int coap_context_get_csm_timeout(const coap_context_t *_context_);* 57 58*void coap_context_set_max_token_size(coap_context_t *_context_, 59size_t _max_token_size_);* 60 61For specific (D)TLS library support, link with 62*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*, 63*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls* 64or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*. Otherwise, link with 65*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support. 66 67DESCRIPTION 68----------- 69This man page focuses on the CoAP Context and how to update or get information 70from the opaque coap_context_t structure. 71 72The CoAP stack's global state is stored in a coap_context_t Context object. 73Resources, Endpoints and Sessions are associated with this context object. 74There can be more than one coap_context_t object per application, it is up to 75the application to manage each one accordingly. 76 77FUNCTIONS 78--------- 79 80*Function: coap_new_context()* 81 82The *coap_new_context*() function creates a new Context that is then used 83to keep all the CoAP Resources, Endpoints and Sessions information. 84The optional _listen_addr_ parameter, if set for a CoAP server, creates an 85Endpoint that is added to the _context_ that is listening for un-encrypted 86traffic on the IP address and port number defined by _listen_addr_. 87 88*Function: coap_free_context()* 89 90The *coap_free_context*() function must be used to release the CoAP stack 91_context_. It clears all entries from the receive queue and send queue and 92deletes the Resources that have been registered with _context_, and frees the 93attached Sessions and Endpoints. 94 95*WARNING:* It is unsafe to call *coap_free_context*() in an atexit() handler 96as other libraries may also call atexit() and clear down some CoAP 97required functionality. 98 99*Function: coap_context_set_max_idle_sessions()* 100 101The *coap_context_set_max_idle_sessions*() function sets the maximum number of 102idle server sessions to _max_idle_sessions_ for _context_. If this number is 103exceeded, the least recently used server session is completely removed. 0 (the 104initial default) means that the number of idle sessions is not monitored. 105 106*Function: coap_context_get_max_idle_sessions()* 107 108The *coap_context_get_max_idle_sessions*() function returns the maximum number 109of idle server sessions for _context_. 110 111*Function: coap_context_set_max_handshake_sessions()* 112 113The *coap_context_set_max_handshake_sessions*() function sets the maximum 114number of outstanding server sessions in (D)TLS handshake to 115_max_handshake_sessions_ for _context_. If this number is exceeded, the least 116recently used server session in handshake is completely removed. 0 (the default) 117means that the number of handshakes is not monitored. 118 119*Function: coap_context_get_max_handshake_sessions()* 120 121The *coap_context_get_max_handshake_sessions*() function returns the maximum 122number of outstanding server sessions in (D)TLS handshake for _context_. 123 124*Function: coap_context_set_session_timeout()* 125 126The *coap_context_set_session_timeout*() function sets the number of seconds of 127inactivity to _session_timeout_ for _context_ before an idle server session is 128removed. 0 (the default) means wait for the default of 300 seconds. 129 130*Function: coap_context_get_session_timeout()* 131 132The *coap_context_get_session_timeout*() function returns the seconds to wait 133before timing out an idle server session for _context_. 134 135*Function: coap_context_set_csm_timeout()* 136 137The *coap_context_set_csm_timeout*() function sets the number of seconds to 138wait for a (TCP) CSM negotiation response from the peer to _csm_timeout_ for 139_context_. 0 (the default) means wait forever. 140 141*Function: coap_context_get_csm_timeout()* 142 143The *coap_context_get_csm_timeout*() function returns the seconds to wait for 144a (TCP) CSM negotiation response from the peer for _context_, 145 146*Function: coap_context_set_max_token_size()* 147 148The *coap_context_set_max_token_size*() function sets the _max_token_size_ 149for _context_. _max_token_size_ must be greater than 8 to indicate 150support for https://rfc-editor.org/rfc/rfc8974[RFC8974] up to _max_token_size_ 151bytes, else 8 to disable https://rfc-editor.org/rfc/rfc8974[RFC8974] 152(if previously set). 153 154*NOTE:* For the client, it will send an initial PDU to test the server 155supports the requested extended token size as per 156"https://rfc-editor.org/rfc/rfc8974.html#section-2.2.2[RFC8794 Section 2.2.2]" 157 158RETURN VALUES 159------------- 160*coap_new_context*() returns a newly created context or 161NULL if there is a creation failure. 162 163*coap_context_get_max_idle_sessions*() returns the maximum number of idle 164server sessions. 165 166*coap_context_get_max_handshake_sessions*() returns the maximum number of 167outstanding server sessions in (D)TLS handshake. 168 169*coap_context_get_session_timeout*() returns the seconds to wait before timing 170out an idle server session. 171 172*coap_context_get_csm_timeout*() returns the seconds to wait for a (TCP) CSM 173negotiation response from the peer. 174 175SEE ALSO 176-------- 177*coap_session*(3) 178 179FURTHER INFORMATION 180------------------- 181See 182 183"https://rfc-editor.org/rfc/rfc7252[RFC7252: The Constrained Application Protocol (CoAP)]" 184 185"https://rfc-editor.org/rfc/rfc8974[RFC8974: Extended Tokens and Stateless Clients in the Constrained Application Protocol (CoAP)]" 186 187for further information. 188 189BUGS 190---- 191Please report bugs on the mailing list for libcoap: 192libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at 193https://github.com/obgm/libcoap/issues 194 195AUTHORS 196------- 197The libcoap project <libcoap-developers@lists.sourceforge.net> 198