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_ms, coap_context_get_csm_timeout_ms, coap_context_set_max_token_size, coap_context_set_app_data, coap_context_get_app_data, coap_context_set_cid_tuple_change - 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_ms(coap_context_t *context,
unsigned int csm_timeout_ms);
unsigned int coap_context_get_csm_timeout_ms(const coap_context_t *context);
void coap_context_set_max_token_size(coap_context_t *context,
size_t max_token_size);
void coap_context_set_app_data(coap_context_t *context, void *app_data);
void *coap_context_get_app_data(const coap_context_t *context);
int coap_context_set_cid_tuple_change(coap_context_t *context_context, uint8_t _every);
For specific (D)TLS library support, link with
-lcoap-3-notls, -lcoap-3-gnutls,
-lcoap-3-openssl, -lcoap-3-mbedtls,
-lcoap-3-wolfssl
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.
WARNING: It is unsafe to call coap_free_context() in any libcoap callback
handlers as set up in coap_handler(3).
WARNING: In a multi-thread, libcoap thread-safe environment, if other threads
are using context, it is not recommended to call coap_free_context() as
various libcoap APIs will unexpectedly fail. It is best to clear down those other
threads first before calling coap_free_context().
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_ms()
The coap_context_set_csm_timeout_ms() function sets the number of milliseconds
to wait for a (TCP) CSM negotiation response from the peer to csm_timeout_ms
for context before timing out and assuming CoAP server is broken. The
default is 1000 milliseconds. The minimum value for csm_timeout_ms is set to
10 milliseconds and the maximum value for csm_timeout_ms is set to 10000
milliseconds.
Function: coap_context_get_csm_timeout_ms()
The coap_context_get_csm_timeout_ms() function returns the milliseconds 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"
Function: coap_context_set_app_data()
The coap_context_set_app_data() function is used to define a app_data
pointer for the context which can then be retrieved at a later date.
Function: coap_context_get_app_data()
The coap_context_get_app_data() function is used to retrieve the app_data
pointer previously defined by coap_context_set_app_data().
Function: coap_context_set_cid_tuple_change()
The coap_context_set_cid_tuple_change() function is used to define to a client
to force the client’s port to change every packets sent, providing the ability
to test a CID (RFC9146) enabled server. Only supported by DTLS libraries that
support CID.
