COAP_CONTEXT(3)

📦

version 4.3.5 · 11 versions

💅 COAP_CONTEXT(3) — the libcoap manual, but make it make sense

okay bestie, so this is a page from the libcoap Manual, and it's all about the CoAP context — the big main-character object that holds literally everything together. no cap, it's the moment. let's get into it 🫶

✨ 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 — literally all the functions for working 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);

and for the specific (D)TLS library support, you link with one of these bad boys: -lcoap-3-notls, -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls, -lcoap-3-wolfssl or -lcoap-3-tinydtls. otherwise? just link with -lcoap-3 and you get the default (D)TLS library support. easy 💅

🦋 DESCRIPTION 🦋

so this man page is hyper-focused on the CoAP Context, and how you update it or get info out of the opaque coap_context_t structure. iykyk.

the CoAP stack's global state lives inside a coap_context_t Context object. Resources, Endpoints and Sessions are all associated with this context object. and yes, you can absolutely have more than one coap_context_t object per application — managing each one is on you, bestie. main character energy means taking responsibility for your own contexts 😌

🎀 FUNCTIONS 🎀

Function: `coap_new_context()`

the coap_new_context() function creates a brand new Context, which is then used to keep all the CoAP Resources, Endpoints and Sessions information. the optional listen_addr parameter — if you set it for a CoAP server — creates an Endpoint that gets added to the context, and that endpoint is listening for un-encrypted traffic on the IP address and port number defined by listen_addr. slay ✨

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, deletes the Resources that have been registered with context, and frees the attached Sessions and Endpoints. it's giving full cleanup, no leftovers 💖

⚠️ WARNING: it is unsafe to call coap_free_context() in an atexit() handler, because other libraries may also call atexit() and clear down some CoAP required functionality. not the vibe. 🙈

⚠️ WARNING: it is unsafe to call coap_free_context() in any libcoap callback handlers as set up in coap_handler(3). literally don't.

⚠️ WARNING: in a multi-thread, libcoap thread-safe environment, if other threads are using context, it is not recommended to call coap_free_context(), because various libcoap APIs will unexpectedly fail. it is best to clear down those other threads first before calling coap_free_context(). periodt.

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 gets exceeded, the least recently used server session is completely removed. 0 (the initial default) means that the number of idle sessions is not monitored at all. no cap, zero means vibes only 🌈

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. short king of a getter.

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. again: unmonitored, unbothered 💅

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. iconic behavior tbh ⭐

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 the 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. so like, stay in your lane, timeout-wise 🔥

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). choose your fighter 🦋

📌 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. little gift to your future self 🎁

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(). the payoff 💖

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. it's giving chaos-testing energy 🧚

⭐ 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_ms() returns the milliseconds to wait for a (TCP) CSM negotiation response from the peer.
coap_context_get_app_data() returns a previously defined pointer.
coap_context_set_cid_tuple_change() returns 1 on success, else 0;

💜 SEE ALSO 💜

coap_session(3) — go read it, bestie, it's the whole other half of the story 🫶

🌸 FURTHER INFORMATION 🌸

see

"RFC7252: The Constrained Application Protocol (CoAP)"
"RFC8974: Extended Tokens and Stateless Clients in the Constrained Application Protocol (CoAP)"

for further information. light reading, obviously 📚✨

💀 BUGS 💀

please raise an issue on GitHub at https://github.com/obgm/libcoap/issues to report any bugs. not me manifesting a bug-free codebase 🙈

please raise a Pull Request at https://github.com/obgm/libcoap/pulls for any fixes. be the fix you want to see in the world 💅

👑 AUTHORS 👑

The libcoap project <libcoap-developers@lists.sourceforge.net> — the actual icons.

and that's the whole page, bestie! this was coap_context version 4.3.5, dated 08/24/2026, from the libcoap gang — mwah, go build something cute 🎀💖🌈

📦 where this page comes from

ubuntu stonking: libcoap3t64 4.3.5-4ubuntu1 · BSD-2-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms

COAP_CONTEXT(3)

💅 COAP_CONTEXT(3) — the libcoap manual, but make it make sense

✨ NAME ✨

🌸 SYNOPSIS 🌸

🦋 DESCRIPTION 🦋

🎀 FUNCTIONS 🎀

Function: coap_new_context()

Function: coap_free_context()

Function: coap_context_set_max_idle_sessions()

Function: coap_context_get_max_idle_sessions()

Function: coap_context_set_max_handshake_sessions()

Function: coap_context_get_max_handshake_sessions()

Function: coap_context_set_session_timeout()

Function: coap_context_get_session_timeout()

Function: coap_context_set_csm_timeout_ms()

Function: coap_context_get_csm_timeout_ms()

Function: coap_context_set_max_token_size()

Function: coap_context_set_app_data()

Function: coap_context_get_app_data()

Function: coap_context_set_cid_tuple_change()