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

FreeBSD Manual Pages

  
 
  

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

NAME
     coap_session,   coap_session_reference,   coap_session_release,   coap_ses-
     sion_disconnected, coap_session_set_type_client, coap_session_set_app_data,
     coap_session_get_app_data,      coap_session_get_addr_local,      coap_ses-
     sion_get_addr_mcast,   coap_session_get_addr_remote,  coap_session_get_con-
     text,    coap_session_get_ifindex,    coap_session_get_proto,     coap_ses-
     sion_get_state,   coap_session_get_tls,   coap_session_get_type,  coap_ses-
     sion_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_li-
     brary_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,  -lcoap-3-wolfssl  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 informa-
     tion 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 subse-
     quent 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  ref-
     erence  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
     from 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 so that
     the  now type Client session does not expire until a coap_session_release()
     is done. NOTE: This function will fail for a DTLS server  type  session  if
     done before the ClientHello is seen.

     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 ad-
     dress 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) is called.

     Function: coap_session_get_context()

     The coap_session_get_context() function is used to get the CoAP context as-
     sociated with the session.

     Function: coap_session_get_ifindex()

     The coap_session_get_ifindex() function is used to get the  network  inter-
     face 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*
	 wolfSSL:  WOLFSSL*
	 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 up-
     dated 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  ses-
     sion'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 er-
     ror.

     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  in-
     formation	(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_endpoint_client(3) and coap_endpoint_server(3)

FURTHER INFORMATION
     See

     "RFC7252: The Constrained Application Protocol (CoAP)"

     for further information.

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.

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

coap_session 4.3.5		   08/02/2026			 COAP_SESSION(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=coap_session_get_psk_hint&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help