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.

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