COAP_CONTEXT(3)

💖 COAP_CONTEXT(3) — bestie, it's the libcoap manual 💖

okay so this is the libcoap Manual page about CoAP contexts, and honestly? it's giving "the whole personality of your app lives here." 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 — 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);

and for your specific (D)TLS library support era, you link with one of these besties: -lcoap-3-notls, -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls, -lcoap-3-wolfssl or -lcoap-3-tinydtls. or, like, if you can't decide, link with -lcoap-3 to get the default (D)TLS library support. slay 🎀

🦋 DESCRIPTION 🦋

This man page is hyper-focused on the CoAP Context and how to update or get info out of the opaque coap_context_t structure. iykyk.

So the CoAP stack's global state is stored in a coap_context_t Context object. Resources, Endpoints and Sessions are all associated with this context object. and get this — you can have more than one coap_context_t object per application, and it's up to the application to manage each one accordingly. main character energy, but make it your responsibility 💅

🔥 FUNCTIONS 🔥

💖 Function: coap_new_context()

coap_new_context() creates a new Context that then keeps all the CoAP Resources, Endpoints and Sessions info. The optional listen_addr parameter — if set for a CoAP server — creates an Endpoint that gets added to the context that's listening for un-encrypted traffic on the IP address and port number defined by listen_addr. periodt.

💀 Function: coap_free_context()

coap_free_context() 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.

⚠️ 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 plot twist we wanted 😭

⚠️ WARNING: It is unsafe to call coap_free_context() in any libcoap callback handlers as set up in coap_handler(3). bestie please 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() — various libcoap APIs will unexpectedly fail. It is best to clear down those other threads first before calling coap_free_context(). fr fr, close the tabs before you crash the browser.

🌈 Function: coap_context_set_max_idle_sessions()

coap_context_set_max_idle_sessions() 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 the number of idle sessions is not monitored. no cap.

⭐ Function: coap_context_get_max_idle_sessions()

coap_context_get_max_idle_sessions() returns the maximum number of idle server sessions for context. cute and simple ✨

🧚 Function: coap_context_set_max_handshake_sessions()

coap_context_set_max_handshake_sessions() 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 the number of handshakes is not monitored. it's giving bouncer at the club 🫶

🎀 Function: coap_context_get_max_handshake_sessions()

coap_context_get_max_handshake_sessions() returns the maximum number of outstanding server sessions in (D)TLS handshake for context.

💜 Function: coap_context_set_session_timeout()

coap_context_set_session_timeout() 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. so yeah, five whole minutes of silence before we ghost them 💀

🍓 Function: coap_context_get_session_timeout()

coap_context_get_session_timeout() returns the seconds to wait before timing out an idle server session for context.

🦋 Function: coap_context_set_csm_timeout_ms()

coap_context_set_csm_timeout_ms() 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. know your limits bestie ✨

🌸 Function: coap_context_get_csm_timeout_ms()

coap_context_get_csm_timeout_ms() returns the milliseconds to wait for a (TCP) CSM negotiation response from the peer for context,

👑 Function: coap_context_set_max_token_size()

coap_context_set_max_token_size() 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 whether the server supports the requested extended token size as per "RFC8794 Section 2.2.2". (yes, that's RFC8794 right there in the original, we do not fix it, we respect it 🙈)

💅 Function: coap_context_set_app_data()

coap_context_set_app_data() is used to define an app_data pointer for the context which can then be retrieved at a later date. it's giving "save it for later" 🎀

🫶 Function: coap_context_get_app_data()

coap_context_get_app_data() is used to retrieve the app_data pointer previously defined by coap_context_set_app_data(). the callback of your dreams.

🔥 Function: coap_context_set_cid_tuple_change()

coap_context_set_cid_tuple_change() 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. testing era 💅

🌟 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 sequel ✨

💜 FURTHER INFORMATION 💜

See

"RFC7252: The Constrained Application Protocol (CoAP)"

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

for further information. required reading, no skipping 📚

💀 BUGS 💀

Please raise an issue on GitHub at https://github.com/obgm/libcoap/issues to report any bugs.

Please raise a Pull Request at https://github.com/obgm/libcoap/pulls for any fixes. we love a collaborative queen 👑

🎀 AUTHORS 🎀

The libcoap project <libcoap-developers@lists.sourceforge.net> 🫶

---

and that's the page! brought to you by coap_context 4.3.5b, dated 04/28/2026 — written in the COAP_CONTEXT(3) section of the libcoap manual. go forth and manage your contexts responsibly, bestie 💅✨