COAP_SESSION(3)

📦
version 4.3.5 · 11 versions
, in ubuntu stonking

👑 COAP_SESSION 💅

okay bestie, welcome to the libcoap Manual — this is the COAP_SESSION(3) page and it's literally all about sessions. grab a snack, we're getting into it 🍓

✨ NAME ✨

coap_session, coap_session_reference, coap_session_release, coap_session_disconnected, coap_session_set_type_client, coap_session_set_app_data, coap_session_get_app_data, coap_session_get_addr_local, coap_session_get_addr_mcast, coap_session_get_addr_remote, coap_session_get_context, coap_session_get_ifindex, coap_session_get_proto, coap_session_get_state, coap_session_get_tls, coap_session_get_type, coap_session_get_psk_hint, coap_session_get_psk_key — work with CoAP sessions 🎀

✨ SYNOPSIS ✨

#include <coap3/coap.h>

coap_session_t *coap_session_reference(coap_session_t *session);

void coap_session_release(coap_session_t *session);

void coap_session_disconnected(coap_session_t *session,
coap_nack_reason_t reason);

int coap_session_set_type_client(coap_session_t *session);

void coap_session_set_app_data(coap_session_t *session, void *data);

void *coap_session_get_app_data(const coap_session_t *session);

const coap_address_t *coap_session_get_addr_local( const coap_session_t
*session);

const coap_address_t *coap_session_get_addr_mcast( const coap_session_t
*session);

const coap_address_t *coap_session_get_addr_remote( const coap_session_t
*session);

coap_context_t *coap_session_get_context(const coap_session_t *session);

int coap_session_get_ifindex(const coap_session_t *session);

coap_proto_t coap_session_get_proto(const coap_session_t *session);

coap_session_state_t coap_session_get_state(const coap_session_t
*session);

void *coap_session_get_tls(const coap_session_t *session,
coap_tls_library_t *tls_lib);

coap_session_type_t coap_session_get_type(const coap_session_t
*session);

const coap_bin_const_t *coap_session_get_psk_hint( const coap_session_t
*session);

const coap_bin_const_t *coap_session_get_psk_key( const coap_session_t
*session);

so for specific (D)TLS library support, you 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 and you get the default (D)TLS library support. periodt 💅

✨ DESCRIPTION ✨

this page is hyper-focused on the CoAP Session — how you update it, how you pull info out of the opaque coap_session_t structure. that's the whole vibe check 🦋

a CoAP Session keeps the state of an ongoing connection between a Client and Server, and it lives in a coap_session_t Session object. a CoAP session is tracked by local port, CoAP protocol, remote IP address and remote port. iykyk 🌸

and the session's network traffic? it can be encrypted or un-encrypted — depends on whether there's an underlying TLS library. no cap 🔥

✨ FUNCTIONS ✨

💖 Function: coap_session_reference()

coap_session_reference() bumps the reference count of the session up by one. why do you care? because when the application increments that reference count, the library will not inadvertently remove the session once it's done processing it. literally protecting your fave from getting yeeted 😭

💖 Function: coap_session_release()

coap_session_release() decrements the session reference count — and when it hits 0, here's what goes down:

  • if the type is Client, the session gets freed off, which then clears all the entries from the receive queue and the send queue. NOTE: all client sessions start off with a reference count of 1. 👑
  • if the type is Server, then the session gets added to an idle pool, ready for subsequent re-use. and if that Server session isn't used for 5 minutes, it gets completely freed off. NOTE: unless the application increments the reference count, this is the case for all type server sessions, since they start with a reference count of 0. 💀

💖 Function: coap_session_disconnected()

coap_session_disconnected() forces the closure of a session, for the reason reason. heads up though — it will cause any outstanding traffic to get dropped. gone. bye. 🫶

💖 Function: coap_session_set_type_client()

coap_session_set_type_client() converts the session from a session endpoint type of Server over to Client. this is typically used in a Call-Home type environment where the roles have to change after a session is established. the reference count gets incremented by 1 so the now-type-Client session doesn't expire until a coap_session_release() is done. 🧚

NOTE: this function will fail for a DTLS server type session if it's done before the ClientHello is seen. so like… timing matters, bestie 🙈

💖 Function: coap_session_set_app_data()

coap_session_set_app_data() defines a data pointer for the session — which you can then retrieve at a later date. stash it now, grab it later ✨

💖 Function: coap_session_get_app_data()

coap_session_get_app_data() retrieves that data pointer you previously defined with coap_session_set_app_data(). found her 💅

💖 Function: coap_session_get_addr_local()

coap_session_get_addr_local() gets the local IP address and port information out of the session. 🌈

💖 Function: coap_session_get_addr_mcast()

coap_session_get_addr_mcast() gets the remote (peer) multicast IP address and port information from the session — but only if the session was originally set up to send requests to a multicast IP. ⭐

💖 Function: coap_session_get_addr_remote()

coap_session_get_addr_remote() gets the remote (peer) IP address and port information from the session.

okay so this one has a lil plot twist 😭 if the session was originally set up to send requests to a multicast IP, then the returned IP will be that of the unicast response from a peer. and that returned IP gets set back to the multicast IP when the next coap_send(3) is called. the way it flips back… iconic 🦋

💖 Function: coap_session_get_context()

coap_session_get_context() gets the CoAP context that's associated with the session. 🎀

💖 Function: coap_session_get_ifindex()

coap_session_get_ifindex() gets the network interface index that the traffic came in over, from the session. 🫶

💖 Function: coap_session_get_proto()

the CoAP protocol values go like this:

  • COAP_PROTO_UDP
  • COAP_PROTO_DTLS
  • COAP_PROTO_TCP
  • COAP_PROTO_TLS
  • COAP_PROTO_WS
  • COAP_PROTO_WSS

and coap_session_get_proto() gets the CoAP protocol from the session. 🔥

💖 Function: coap_session_get_state()

the session state values, in all their glory:

  • COAP_SESSION_STATE_NONE
  • COAP_SESSION_STATE_CONNECTING
  • COAP_SESSION_STATE_HANDSHAKE
  • COAP_SESSION_STATE_CSM
  • COAP_SESSION_STATE_ESTABLISHED

and coap_session_get_state() gets the current state of the session. 💜

💖 Function: coap_session_get_tls()

the TLS info pointers, per library:

  • OpenSSL: SSL*
  • GnuTLS: gnutls_session_t (implicit *)
  • Mbed TLS: mbedtls_ssl_context*
  • wolfSSL: WOLFSSL*
  • TinyDTLS: struct dtls_context*

coap_session_get_tls() gets the pointer to the TLS information from the session — and heads up, this is TLS library specific. tls_lib gets updated with the underlying (D)TLS library type. 👑

💖 Function: coap_session_get_type()

the session types, bestie:

  • COAP_SESSION_TYPE_CLIENT
  • COAP_SESSION_TYPE_SERVER
  • COAP_SESSION_TYPE_HELLO /* Negotiating a (D)TLS session */

coap_session_get_type() gets the session type from the session. 🌸

💖 Function: coap_session_get_psk_hint()

coap_session_get_psk_hint() gets the current server session's pre-shared-key identity hint. 🔑

💖 Function: coap_session_get_psk_key()

coap_session_get_psk_key() gets the current session's pre-shared-key key information. 🗝️

✨ RETURN VALUES ✨

  • coap_session_reference() returns a pointer to the session. 🫶
  • coap_session_set_type_client() returns 1 on success, otherwise 0.
  • coap_session_get_app_data() returns a previously defined pointer.
  • coap_session_get_addr_local() and coap_session_get_addr_remote() return a pointer to the IP address / port, or NULL on error. 😭
  • coap_session_get_addr_mcast() returns a pointer to the remote multicast IP address / port, or NULL on error or if this is not a multicast session.
  • coap_session_get_context() returns a pointer to the current CoAP Context, or NULL on error.
  • coap_session_get_ifindex() returns the network interface the traffic last came in over, or -1 on error.
  • coap_session_get_proto() returns the current session's protocol, or 0 on error.
  • coap_session_get_state() returns the current session's state, or 0 on error.
  • coap_session_get_tls() returns a pointer to the current session's TLS information (TLS library dependent), or NULL if there is none or if there's an error.
  • coap_session_get_type() returns the current session's type, or 0 on error.
  • coap_session_get_psk_hint() returns the current server session's pre-shared-key identity hint, or NULL if not defined.
  • coap_session_get_psk_key() returns the current session's pre-shared-key key information, or NULL if not defined.

✨ SEE ALSO ✨

coap_context(3), coap_endpoint_client(3) and coap_endpoint_server(3) — go read those next, bestie 🦋

✨ FURTHER INFORMATION ✨

see

"RFC7252: The Constrained Application Protocol (CoAP)"

for further information. yes, actual lore 📚✨

✨ BUGS ✨

found a bug? please raise an issue on GitHub at https://github.com/obgm/libcoap/issues to report any bugs. 🙈

got a fix? please raise a Pull Request at https://github.com/obgm/libcoap/pulls for any fixes. you'd be the main character fr 💅🔥

✨ AUTHORS ✨

the libcoap project <libcoap-developers@lists.sourceforge.net> 👑

okay that's the whole page, you ate that 🍓 signing off from coap_session version 4.3.5, dated 08/24/2026 — libcoap Manual, love u, bye bestie! 💖🎀🦋

📦 where this page comes from