Man page - coap_session(3)

Packages contains this manual

Package: libcoap3t64
apt-get install libcoap3t64

Manuals in package:

Documentations in package:

libcoap3t64

Manual

COAP_SESSION

NAME
SYNOPSIS
DESCRIPTION
FUNCTIONS
RETURN VALUES
SEE ALSO
FURTHER INFORMATION
BUGS
AUTHORS

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

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

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

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

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>