libcoap  4.3.0
coap_session(3)
coap_session

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

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.

COAP_PROTO_UDP
COAP_PROTO_DTLS
COAP_PROTO_TCP
COAP_PROTO_TLS

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() function returns a pointer to the session.

coap_session_set_type_client() function returns 1 on success, otherwise 0.

coap_session_get_app_data() function return 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_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 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 <libcoap-developers@lists.sourceforge.net>

coap_session(3)