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
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
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
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) 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*
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
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.