Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
COAP_SESSION(3)			libcoap	Manual		       COAP_SESSION(3)

       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_remote - Work	with
       CoAP sessions

       #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

       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

       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

       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

       const coap_bin_const_t *coap_session_get_psk_hint( const	coap_session_t

       const coap_bin_const_t *coap_session_get_psk_key( const coap_session_t

       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.

       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.

       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.

       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.

       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.

       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.

       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.

       The coap_session_get_app_data() function	is used	to retrieve the	data
       pointer previously defined by coap_session_set_app_data().

       The coap_session_get_addr_local() function is used to get the local IP
       address and port	information from the session.

       The coap_session_get_addr_remote() function is used to get the remote
       (peer) IP address and port information from the session.

       The coap_session_get_context() function is used to get the CoAP context
       associated with the session.

       The coap_session_get_ifindex() function is used to get the network
       interface index that the	traffic	came in	over from the session.


       The coap_session_get_proto() function is	used to	get the	CoAP protocol
       from the	session.


       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_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.

       coap_session_reference()	function returns a pointer to the session.

       coap_session_set_type_client() function returns 1 on success, otherwise

       coap_session_get_app_data() function return a previously	defined

       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_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

       coap_session_get_state()	returns	the current session's state or 0 on

       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

       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.

       coap_context(3),	coap_endpoint_client(3)	and coap_endpoint_server(3)

       See "RFC7252: The Constrained Application Protocol (CoAP)" for further

       Please report bugs on the mailing list for libcoap:	or raise an issue on GitHub at

       The libcoap project <>

coap_session 4.3.0		  09/22/2021		       COAP_SESSION(3)


Want to link to this manual page? Use this URL:

home | help