API for CoAP Session access. More...

Collaboration diagram for Sessions:

Data Structures
struct	coap_fixed_point_t
	Abstraction of a fixed point number that can be used where necessary instead of a float. More...

Macros
#define	COAP_PROTO_NOT_RELIABLE(p) ((p)==COAP_PROTO_UDP \|\| (p)==COAP_PROTO_DTLS)

#define	COAP_PROTO_RELIABLE(p)

Typedefs
typedef struct coap_fixed_point_t	coap_fixed_point_t
	Abstraction of a fixed point number that can be used where necessary instead of a float.

typedef enum coap_session_type_t	coap_session_type_t
	coap_session_type_t values

typedef enum coap_session_state_t	coap_session_state_t
	coap_session_state_t values

typedef void(*	coap_app_data_free_callback_t) (void *data)
	Callback to free off the app data when the entry is being deleted / freed off.

Enumerations
enum	coap_session_type_t { COAP_SESSION_TYPE_NONE = 0 , COAP_SESSION_TYPE_CLIENT , COAP_SESSION_TYPE_SERVER , COAP_SESSION_TYPE_HELLO }
	coap_session_type_t values More...

enum	coap_session_state_t { COAP_SESSION_STATE_NONE = 0 , COAP_SESSION_STATE_CONNECTING , COAP_SESSION_STATE_HANDSHAKE , COAP_SESSION_STATE_CSM , COAP_SESSION_STATE_ESTABLISHED }
	coap_session_state_t values More...

Functions
COAP_API coap_session_t *	coap_session_reference (coap_session_t *session)
	Increment reference counter on a session.

COAP_API void	coap_session_release (coap_session_t *session)
	Decrement reference counter on a session.

COAP_API void	coap_session_disconnected (coap_session_t *session, coap_nack_reason_t reason)
	Notify session that it has failed.

COAP_DEPRECATED void	coap_session_set_app_data (coap_session_t session, void data)
	Stores `data` with the given session.

void *	coap_session_get_app_data (const coap_session_t *session)
	Returns any application-specific data that has been stored with `session` using the function coap_session_set_app_data() or coap_session_set_app_data2().

COAP_API void *	coap_session_set_app_data2 (coap_session_t session, void data, coap_app_data_free_callback_t callback)
	Stores `data` with the given session, returning the previously stored value or NULL.

const coap_address_t *	coap_session_get_addr_remote (const coap_session_t *session)
	Get the remote IP address and port from the session.

const coap_address_t *	coap_session_get_addr_mcast (const coap_session_t *session)
	Get the remote multicast IP address and port from the session if the original target IP was multicast.

const coap_address_t *	coap_session_get_addr_local (const coap_session_t *session)
	Get the local IP address and port from the session.

coap_proto_t	coap_session_get_proto (const coap_session_t *session)
	Get the session protocol type.

coap_session_type_t	coap_session_get_type (const coap_session_t *session)
	Get the session type.

coap_session_state_t	coap_session_get_state (const coap_session_t *session)
	Get the session state.

int	coap_session_get_ifindex (const coap_session_t *session)
	Get the session if index.

void *	coap_session_get_tls (const coap_session_t session, coap_tls_library_t tls_lib)
	Get the session TLS security ptr (TLS type dependent)

coap_context_t *	coap_session_get_context (const coap_session_t *session)
	Get the session context.

COAP_API int	coap_session_set_type_client (coap_session_t *session)
	Set the session type to client.

void	coap_session_set_mtu (coap_session_t *session, unsigned mtu)
	Set the session MTU.

COAP_API size_t	coap_session_max_pdu_size (const coap_session_t *session)
	Get maximum acceptable PDU size.

COAP_API coap_session_t *	coap_new_client_session (coap_context_t ctx, const coap_address_t local_if, const coap_address_t *server, coap_proto_t proto)
	Creates a new client session to the designated server.

COAP_API coap_session_t *	coap_new_client_session_psk (coap_context_t ctx, const coap_address_t local_if, const coap_address_t server, coap_proto_t proto, const char identity, const uint8_t *key, unsigned key_len)
	Creates a new client session to the designated server with PSK credentials.

COAP_API coap_session_t *	coap_new_client_session_psk2 (coap_context_t ctx, const coap_address_t local_if, const coap_address_t server, coap_proto_t proto, coap_dtls_cpsk_t setup_data)
	Creates a new client session to the designated server with PSK credentials.

const coap_bin_const_t *	coap_session_get_psk_hint (const coap_session_t *session)
	Get the server session's current Identity Hint (PSK).

const coap_bin_const_t *	coap_session_get_psk_identity (const coap_session_t *session)
	Get the server session's current PSK identity (PSK).

const coap_bin_const_t *	coap_session_get_psk_key (const coap_session_t *session)
	Get the session's current pre-shared key (PSK).

COAP_API coap_session_t *	coap_new_client_session_pki (coap_context_t ctx, const coap_address_t local_if, const coap_address_t server, coap_proto_t proto, coap_dtls_pki_t setup_data)
	Creates a new client session to the designated server with PKI credentials.

void	coap_session_init_token (coap_session_t session, size_t length, const uint8_t token)
	Initializes the token value to use as a starting point.

void	coap_session_new_token (coap_session_t session, size_t length, uint8_t *token)
	Creates a new token for use.

COAP_API coap_endpoint_t *	coap_new_endpoint (coap_context_t context, const coap_address_t listen_addr, coap_proto_t proto)
	Create a new endpoint for communicating with peers.

void	coap_endpoint_set_default_mtu (coap_endpoint_t *endpoint, unsigned mtu)
	Set the endpoint's default MTU.

COAP_API void	coap_free_endpoint (coap_endpoint_t *endpoint)
	Release an endpoint and all the structures associated with it.

coap_session_t *	coap_session_get_by_peer (const coap_context_t context, const coap_address_t remote_addr, int ifindex)
	Get the session associated with the specified `remote_addr` and `index`.

Detailed Description

API for CoAP Session access.

Macro Definition Documentation

◆ COAP_PROTO_NOT_RELIABLE

#define COAP_PROTO_NOT_RELIABLE ( p ) ((p)==COAP_PROTO_UDP || (p)==COAP_PROTO_DTLS)

Definition at line 37 of file coap_session.h.

◆ COAP_PROTO_RELIABLE

#define COAP_PROTO_RELIABLE ( p )

Value:

((p)==COAP_PROTO_TCP || (p)==COAP_PROTO_TLS || \

(p)==COAP_PROTO_WS || (p)==COAP_PROTO_WSS)

COAP_PROTO_WS

@ COAP_PROTO_WS

Definition coap_pdu.h:318

COAP_PROTO_TLS

@ COAP_PROTO_TLS

Definition coap_pdu.h:317

COAP_PROTO_WSS

@ COAP_PROTO_WSS

Definition coap_pdu.h:319

COAP_PROTO_TCP

@ COAP_PROTO_TCP

Definition coap_pdu.h:316

Definition at line 38 of file coap_session.h.

Typedef Documentation

◆ coap_app_data_free_callback_t

typedef void(* coap_app_data_free_callback_t) (void *data)

Callback to free off the app data when the entry is being deleted / freed off.

Parameters

data	The app data to be freed off.

Definition at line 120 of file coap_session.h.

◆ coap_fixed_point_t

typedef struct coap_fixed_point_t coap_fixed_point_t

Abstraction of a fixed point number that can be used where necessary instead of a float.

1,000 fractional bits equals one integer

◆ coap_session_state_t

typedef enum coap_session_state_t coap_session_state_t

coap_session_state_t values

◆ coap_session_type_t

typedef enum coap_session_type_t coap_session_type_t

coap_session_type_t values

Enumeration Type Documentation

◆ coap_session_state_t

enum coap_session_state_t

coap_session_state_t values

Enumerator
COAP_SESSION_STATE_NONE
COAP_SESSION_STATE_CONNECTING
COAP_SESSION_STATE_HANDSHAKE
COAP_SESSION_STATE_CSM
COAP_SESSION_STATE_ESTABLISHED

Definition at line 55 of file coap_session.h.

◆ coap_session_type_t

enum coap_session_type_t

coap_session_type_t values

Enumerator
COAP_SESSION_TYPE_NONE	Not defined.
COAP_SESSION_TYPE_CLIENT	client-side
COAP_SESSION_TYPE_SERVER	server-side
COAP_SESSION_TYPE_HELLO	server-side ephemeral session for responding to a client hello

Definition at line 44 of file coap_session.h.

Function Documentation

◆ coap_endpoint_set_default_mtu()

void coap_endpoint_set_default_mtu	(	coap_endpoint_t *	endpoint,
		unsigned	mtu
	)

Set the endpoint's default MTU.

This is the maximum message size that can be sent, excluding IP and UDP overhead.

Parameters

endpoint	The CoAP endpoint.
mtu	maximum message size

◆ coap_free_endpoint()

COAP_API void coap_free_endpoint ( coap_endpoint_t * endpoint )

Release an endpoint and all the structures associated with it.

Parameters

endpoint The endpoint to release.

◆ coap_new_client_session()

COAP_API coap_session_t * coap_new_client_session	(	coap_context_t *	ctx,
		const coap_address_t *	local_if,
		const coap_address_t *	server,
		coap_proto_t	proto
	)

Creates a new client session to the designated server.

Parameters

ctx	The CoAP context.
local_if	Address of local interface. It is recommended to use NULL to let the operating system choose a suitable local interface. If an address is specified, the port number should be zero, which means that a free port is automatically selected.
server	The server's address. If the port number is zero, the default port for the protocol will be used.
proto	Protocol.

Returns: A new CoAP session or NULL if failed. Call coap_session_release to free.

◆ coap_new_client_session_pki()

COAP_API coap_session_t * coap_new_client_session_pki	(	coap_context_t *	ctx,
		const coap_address_t *	local_if,
		const coap_address_t *	server,
		coap_proto_t	proto,
		coap_dtls_pki_t *	setup_data
	)

Creates a new client session to the designated server with PKI credentials.

Parameters

ctx	The CoAP context.
local_if	Address of local interface. It is recommended to use NULL to let the operating system choose a suitable local interface. If an address is specified, the port number should be zero, which means that a free port is automatically selected.
server	The server's address. If the port number is zero, the default port for the protocol will be used.
proto	CoAP Protocol.
setup_data	PKI parameters.

Returns: A new CoAP session or NULL if failed. Call coap_session_release() to free.

◆ coap_new_client_session_psk()

COAP_API coap_session_t * coap_new_client_session_psk	(	coap_context_t *	ctx,
		const coap_address_t *	local_if,
		const coap_address_t *	server,
		coap_proto_t	proto,
		const char *	identity,
		const uint8_t *	key,
		unsigned	key_len
	)

Creates a new client session to the designated server with PSK credentials.

Deprecated:: Use coap_new_client_session_psk2() instead.

Parameters

ctx	The CoAP context.
local_if	Address of local interface. It is recommended to use NULL to let the operating system choose a suitable local interface. If an address is specified, the port number should be zero, which means that a free port is automatically selected.
server	The server's address. If the port number is zero, the default port for the protocol will be used.
proto	Protocol.
identity	PSK client identity
key	PSK shared key
key_len	PSK shared key length

Returns: A new CoAP session or NULL if failed. Call coap_session_release to free.

◆ coap_new_client_session_psk2()

COAP_API coap_session_t * coap_new_client_session_psk2	(	coap_context_t *	ctx,
		const coap_address_t *	local_if,
		const coap_address_t *	server,
		coap_proto_t	proto,
		coap_dtls_cpsk_t *	setup_data
	)

Creates a new client session to the designated server with PSK credentials.

Parameters

ctx	The CoAP context.
local_if	Address of local interface. It is recommended to use NULL to let the operating system choose a suitable local interface. If an address is specified, the port number should be zero, which means that a free port is automatically selected.
server	The server's address. If the port number is zero, the default port for the protocol will be used.
proto	CoAP Protocol.
setup_data	PSK parameters.

Returns: A new CoAP session or NULL if failed. Call coap_session_release() to free.

◆ coap_new_endpoint()

COAP_API coap_endpoint_t * coap_new_endpoint	(	coap_context_t *	context,
		const coap_address_t *	listen_addr,
		coap_proto_t	proto
	)

Create a new endpoint for communicating with peers.

Parameters

context	The coap context that will own the new endpoint,
listen_addr	Address the endpoint will listen for incoming requests on or originate outgoing requests from. Use NULL to specify that no incoming request will be accepted and use a random endpoint.
proto	Protocol used on this endpoint,

Returns: The new endpoint or NULL on failure.

◆ coap_session_disconnected()

COAP_API void coap_session_disconnected	(	coap_session_t *	session,
		coap_nack_reason_t	reason
	)

Notify session that it has failed.

This cleans up any outstanding / queued transmissions, observations etc..

Parameters

session	The CoAP session.
reason	The reason why the session was disconnected.

Definition at line 1004 of file coap_session.c.

Here is the call graph for this function:

◆ coap_session_get_addr_local()

const coap_address_t * coap_session_get_addr_local ( const coap_session_t * session )

Get the local IP address and port from the session.

Parameters

session The CoAP session.

Returns: The session's local address or NULL on failure.

Definition at line 2021 of file coap_session.c.

◆ coap_session_get_addr_mcast()

const coap_address_t * coap_session_get_addr_mcast ( const coap_session_t * session )

Get the remote multicast IP address and port from the session if the original target IP was multicast.

Note: This is only available for a client.

Parameters

session The CoAP session.

Returns: The session's remote multicast address or NULL on failure or if this is not a multicast session.

Definition at line 2028 of file coap_session.c.

◆ coap_session_get_addr_remote()

const coap_address_t * coap_session_get_addr_remote ( const coap_session_t * session )

Get the remote IP address and port from the session.

Note: For clients, this can be the responding IP address for a multicast request before the next coap_send() is called when the multicast address is restored.

Parameters

session The CoAP session.

Returns: The session's remote address or NULL on failure.

Definition at line 2014 of file coap_session.c.

◆ coap_session_get_app_data()

void * coap_session_get_app_data ( const coap_session_t * session )

Returns any application-specific data that has been stored with session using the function coap_session_set_app_data() or coap_session_set_app_data2().

This function will return NULL if no data has been stored.

Parameters

session The CoAP session.

Returns: Pointer to the stored data or NULL.

Definition at line 407 of file coap_session.c.

◆ coap_session_get_by_peer()

coap_session_t * coap_session_get_by_peer	(	const coap_context_t *	context,
		const coap_address_t *	remote_addr,
		int	ifindex
	)

Get the session associated with the specified remote_addr and index.

Parameters

context	The context to search.
remote_addr	The remote (peer) address to search for.
ifindex	The Interface index that is used to access remote_addr.

Returns: The found session or NULL if not found.

Definition at line 2305 of file coap_session.c.

Here is the call graph for this function:

◆ coap_session_get_context()

coap_context_t * coap_session_get_context ( const coap_session_t * session )

Get the session context.

Parameters

session The CoAP session.

Returns: The session's context

Definition at line 2040 of file coap_session.c.

◆ coap_session_get_ifindex()

int coap_session_get_ifindex ( const coap_session_t * session )

Get the session if index.

Parameters

session The CoAP session.

Returns: The session's if index, or -1 on error.

Definition at line 2092 of file coap_session.c.

◆ coap_session_get_proto()

coap_proto_t coap_session_get_proto ( const coap_session_t * session )

Get the session protocol type.

Parameters

session The CoAP session.

Returns: The session's protocol type

Definition at line 2047 of file coap_session.c.

◆ coap_session_get_psk_hint()

const coap_bin_const_t * coap_session_get_psk_hint ( const coap_session_t * session )

Get the server session's current Identity Hint (PSK).

Parameters

session The current coap_session_t object.

Returns: hint if successful, else NULL.

◆ coap_session_get_psk_identity()

const coap_bin_const_t * coap_session_get_psk_identity ( const coap_session_t * session )

Get the server session's current PSK identity (PSK).

Parameters

session The current coap_session_t object.

Returns: PSK identity if successful, else NULL.

Definition at line 1856 of file coap_session.c.

◆ coap_session_get_psk_key()

const coap_bin_const_t * coap_session_get_psk_key ( const coap_session_t * session )

Get the session's current pre-shared key (PSK).

Parameters

session The current coap_session_t object.

Returns: psk_key if successful, else NULL.

Definition at line 1868 of file coap_session.c.

◆ coap_session_get_state()

coap_session_state_t coap_session_get_state ( const coap_session_t * session )

Get the session state.

Parameters

session The CoAP session.

Returns: The session's state

Definition at line 2085 of file coap_session.c.

◆ coap_session_get_tls()

void * coap_session_get_tls	(	const coap_session_t *	session,
		coap_tls_library_t *	tls_lib
	)

Get the session TLS security ptr (TLS type dependent)

OpenSSL: SSL* GnuTLS: gnutls_session_t (implicit *) Mbed TLS: mbedtls_ssl_context* TinyDTLS: struct dtls_context*

Parameters

session	The CoAP session.
tls_lib	Updated with the library type.

Returns: The session TLS ptr or NULL if not set up

Definition at line 2099 of file coap_session.c.

Here is the call graph for this function:

◆ coap_session_get_type()

coap_session_type_t coap_session_get_type ( const coap_session_t * session )

Get the session type.

Parameters

session The CoAP session.

Returns: The session's type

Definition at line 2054 of file coap_session.c.

◆ coap_session_init_token()

void coap_session_init_token	(	coap_session_t *	session,
		size_t	length,
		const uint8_t *	token
	)

Initializes the token value to use as a starting point.

Parameters

session	The current coap_session_t object.
length	The length of the token (0 - 8 bytes).
token	The token data.

Definition at line 1977 of file coap_session.c.

Here is the call graph for this function:

◆ coap_session_max_pdu_size()

COAP_API size_t coap_session_max_pdu_size ( const coap_session_t * session )

Get maximum acceptable PDU size.

Parameters

session The CoAP session.

Returns: maximum PDU size, not including header (but including token).

Definition at line 711 of file coap_session.c.

Here is the call graph for this function:

◆ coap_session_new_token()

void coap_session_new_token	(	coap_session_t *	session,
		size_t *	length,
		uint8_t *	token
	)

Creates a new token for use.

Parameters

session	The current coap_session_t object.
length	Updated with the length of the new token.
token	Updated with the new token data (must be 8 bytes long).

Definition at line 1988 of file coap_session.c.

Here is the call graph for this function:

◆ coap_session_reference()

COAP_API coap_session_t * coap_session_reference ( coap_session_t * session )

Increment reference counter on a session.

Parameters

session The CoAP session.

Returns: same as session

Definition at line 348 of file coap_session.c.

Here is the call graph for this function:

◆ coap_session_release()

COAP_API void coap_session_release ( coap_session_t * session )

Decrement reference counter on a session.

Note that the session may be deleted as a result and should not be used after this call.

Parameters

session The CoAP session.

Definition at line 362 of file coap_session.c.

Here is the call graph for this function:

◆ coap_session_set_app_data()

COAP_DEPRECATED void coap_session_set_app_data	(	coap_session_t *	session,
		void *	data
	)

Stores data with the given session.

This function overwrites any value that has previously been stored with session.

Deprecated:: Use coap_session_set_app_data2() instead.

Parameters

session	The CoAP session.
data	The pointer to the data to store.

Definition at line 399 of file coap_session.c.

Here is the call graph for this function:

◆ coap_session_set_app_data2()

COAP_API void * coap_session_set_app_data2	(	coap_session_t *	session,
		void *	data,
		coap_app_data_free_callback_t	callback
	)

Stores data with the given session, returning the previously stored value or NULL.

The data callback can be defined if the data is to be released when the session is deleted.

Note: It is the responsibility of the caller to free off (if appropriate) any returned data.

Parameters

session	The CoAP session.
data	The pointer to the data to store or NULL to just clear out the previous data.
callback	The optional release call-back for data on session removal or NULL.

Returns: The previous data (if any) stored in the session.

Definition at line 413 of file coap_session.c.

Here is the call graph for this function:

◆ coap_session_set_mtu()

void coap_session_set_mtu	(	coap_session_t *	session,
		unsigned	mtu
	)

Set the session MTU.

This is the maximum message size that can be sent, excluding IP and UDP overhead.

Parameters

session	The CoAP session.
mtu	maximum message size

Definition at line 755 of file coap_session.c.

Here is the caller graph for this function:

◆ coap_session_set_type_client()

COAP_API int coap_session_set_type_client ( coap_session_t * session )

Set the session type to client.

Typically used in a call-home server. The session initially needs to be of type COAP_SESSION_TYPE_SERVER, which is then made COAP_SESSION_TYPE_CLIENT. Note: If this function is successful, the session reference count is incremented and a subsequent coap_session_release() taking the reference count to 0 will cause the (now client) session to be freed off. Note: This function will fail for a DTLS server type session if done before the ClientHello is seen.

Parameters

session The CoAP session.

Returns: 1 if updated, 0 on failure.

Definition at line 2061 of file coap_session.c.

Here is the call graph for this function:

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ COAP_PROTO_NOT_RELIABLE

◆ COAP_PROTO_RELIABLE

Typedef Documentation

◆ coap_app_data_free_callback_t

◆ coap_fixed_point_t

◆ coap_session_state_t

◆ coap_session_type_t

Enumeration Type Documentation

◆ coap_session_state_t

◆ coap_session_type_t

Function Documentation

◆ coap_endpoint_set_default_mtu()

◆ coap_free_endpoint()

◆ coap_new_client_session()

◆ coap_new_client_session_pki()

◆ coap_new_client_session_psk()

◆ coap_new_client_session_psk2()

◆ coap_new_endpoint()

◆ coap_session_disconnected()

◆ coap_session_get_addr_local()

◆ coap_session_get_addr_mcast()

◆ coap_session_get_addr_remote()

◆ coap_session_get_app_data()

◆ coap_session_get_by_peer()

◆ coap_session_get_context()

◆ coap_session_get_ifindex()

◆ coap_session_get_proto()

◆ coap_session_get_psk_hint()

◆ coap_session_get_psk_identity()

◆ coap_session_get_psk_key()

◆ coap_session_get_state()

◆ coap_session_get_tls()

◆ coap_session_get_type()

◆ coap_session_init_token()

◆ coap_session_max_pdu_size()

◆ coap_session_new_token()

◆ coap_session_reference()

◆ coap_session_release()

◆ coap_session_set_app_data()

◆ coap_session_set_app_data2()

◆ coap_session_set_mtu()

◆ coap_session_set_type_client()