--- name: "coap_session_reference" section: "3" platform: "linux" package: "libcoap3t64" version: "4.3.4-1.1+deb13u3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/coap_session" --- # coap\_session\_reference(3) Work with CoAP sessions Part of [coap\_session(3)](/coap_session/3.md). ## 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 \** **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***);** For specific (D)TLS library support, link with **-lcoap-3-notls**, **-lcoap-3-gnutls**, **-lcoap-3-openssl**, **-lcoap-3-mbedtls** 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 Session and how to update or get information from the opaque coap\_session\_t structure. A CoAP Session maintains the state of an ongoing connection between a Client and Server which is stored in a coap\_session\_t Session object. A CoAP session is tracked by local port, CoAP protocol, remote IP address and remote port. The Session network traffic can be encrypted or un-encrypted if there is an underlying TLS library. ## FUNCTIONS **Function: coap\_session\_reference()** The **coap\_session\_reference**() function is used to increment the reference count of the *session*. Incrementing the reference count by an application means that the library will not inadvertently remove the session when it has finished processing the session. **Function: coap\_session\_release()** The **coap\_session\_release**() function is be used to decrement the *session* reference count, which when it gets to 0, will:- If type Client, free off the session which then clears all entries from the receive queue and send queue. **NOTE:** All client sessions start off with a reference count of 1. If type Server, then the *session* is added to an idle pool ready for subsequent re-use. If the Server *session* is not used for 5 minutes, then it will get completely freed off. **NOTE:** Unless the application increments the reference count, this is the case for all type server sessions as they start with a reference count of 0. **Function: coap\_session\_disconnected()** The **coap\_session\_disconnected**() function is used to force the closure of a *session* for the reason *reason*. It will cause any outstanding traffic to get dropped. **Function: coap\_session\_set\_type\_client()** The **coap\_session\_set\_type\_client**() function is used to convert the *session* frrm a session endpoint type of Server to Client. This typically is used in a Call-Home type environment where the roles have to change following the establishment of a session. The reference count is incremented by 1. **Function: coap\_session\_set\_app\_data()** The **coap\_session\_set\_app\_data**() function is used to define a *data* pointer for the *session* which can then be retrieved at a later date. **Function: coap\_session\_get\_app\_data()** The **coap\_session\_get\_app\_data**() function is used to retrieve the data pointer previously defined by **coap\_session\_set\_app\_data**(). **Function: coap\_session\_get\_addr\_local()** The **coap\_session\_get\_addr\_local**() function is used to get the local IP address and port information from the *session*. **Function: coap\_session\_get\_addr\_mcast()** The **coap\_session\_get\_addr\_mcast**() function is used to get the remote (peer) multicast IP address and port information from the *session* if the *session* was originally set up to send requests to a multicast IP. **Function: coap\_session\_get\_addr\_remote()** The **coap\_session\_get\_addr\_remote**() function is used to get the remote (peer) IP address and port information from the *session*. 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. The returned IP will get set back to the multicast IP when the next [**coap\_send**(3)](/coap_send/3.md) is called. **Function: coap\_session\_get\_context()** The **coap\_session\_get\_context**() function is used to get the CoAP context associated with the *session*. **Function: coap\_session\_get\_ifindex()** The **coap\_session\_get\_ifindex**() function is used to get the network interface index that the traffic came in over from the *session*. ``` COAP_PROTO_UDP COAP_PROTO_DTLS COAP_PROTO_TCP COAP_PROTO_TLS COAP_PROTO_WS COAP_PROTO_WSS ``` The **coap\_session\_get\_proto**() function is used to get the CoAP protocol from the *session*. ``` COAP_SESSION_STATE_NONE COAP_SESSION_STATE_CONNECTING COAP_SESSION_STATE_HANDSHAKE COAP_SESSION_STATE_CSM COAP_SESSION_STATE_ESTABLISHED ``` The **coap\_session\_get\_state**() function is used to get the current state of the *session*. ``` OpenSSL: SSL* GnuTLS: gnutls_session_t (implicit *) Mbed TLS: mbedtls_ssl_context* TinyDTLS: struct dtls_context* ``` The **coap\_session\_get\_tls**() function is used to get the pointer to the TLS information from the *session*. This is TLS library specific. *tls\_lib* is updated with the underlying (D)TLS library type. ``` COAP_SESSION_TYPE_CLIENT COAP_SESSION_TYPE_SERVER COAP_SESSION_TYPE_HELLO /* Negotiating a (D)TLS session */ ``` The **coap\_session\_get\_type**() function is used to get the session type from the *session*. The **coap\_session\_get\_psk\_hint**() function is used to get the current server *session*'s pre-shared-key identity hint. The **coap\_session\_get\_psk\_key**() function is used to get 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 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 there is 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_context/3.md), [**coap\_endpoint\_client**(3)](/coap_endpoint_client/3.md) and [**coap\_endpoint\_server**(3)](/coap_endpoint_server/3.md) ## FURTHER INFORMATION See "RFC7252: The Constrained Application Protocol (CoAP)" for further information. ## BUGS Please report bugs on the mailing list for libcoap: libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at https://github.com/obgm/libcoap/issues ## AUTHORS The libcoap project \