API functions for CoAP Sessions. More...

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) ((p)==COAP_PROTO_TCP \|\| (p)==COAP_PROTO_TLS)

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

typedef enum coap_session_type_t	coap_session_type_t
	coap_session_type_t values More...

typedef enum coap_session_state_t	coap_session_state_t
	coap_session_state_t values More...

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_session_t *	coap_session_reference (coap_session_t *session)
	Increment reference counter on a session. More...

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

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

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

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(). More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

void	coap_free_endpoint (coap_endpoint_t *ep)

Detailed Description

API functions for CoAP Sessions.

Macro Definition Documentation

◆ COAP_PROTO_NOT_RELIABLE

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

Definition at line 35 of file coap_session.h.

◆ COAP_PROTO_RELIABLE

#define COAP_PROTO_RELIABLE ( p ) ((p)==COAP_PROTO_TCP || (p)==COAP_PROTO_TLS)

Definition at line 36 of file coap_session.h.

Typedef Documentation

◆ 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 52 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 41 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

Definition at line 1319 of file coap_session.c.

◆ coap_free_endpoint()

void coap_free_endpoint ( coap_endpoint_t * ep )

Definition at line 1324 of file coap_session.c.

Here is the caller graph for this function:

◆ coap_new_client_session()

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.

Definition at line 898 of file coap_session.c.

Here is the call graph for this function:

◆ coap_new_client_session_pki()

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.

Definition at line 1067 of file coap_session.c.

Here is the call graph for this function:

◆ coap_new_client_session_psk()

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.

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.

Definition at line 913 of file coap_session.c.

Here is the call graph for this function:

◆ coap_new_client_session_psk2()

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.

Definition at line 940 of file coap_session.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_new_endpoint()

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

Definition at line 1229 of file coap_session.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_session_disconnected()

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 456 of file coap_session.c.

Here is the call graph for this function:

Here is the caller 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 from the session.

Parameters

session The CoAP session.

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

Definition at line 1170 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 from the session.

Parameters

session The CoAP session.

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

Definition at line 1163 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().

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 104 of file coap_session.c.

◆ 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 1177 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 1214 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 1184 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.

Definition at line 1054 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 1061 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 1208 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 1220 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 1191 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 1146 of file coap_session.c.

Here is the call graph for this function:

◆ coap_session_max_pdu_size()

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 244 of file coap_session.c.

Here is the caller 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 1151 of file coap_session.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_session_reference()

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 70 of file coap_session.c.

Here is the caller graph for this function:

◆ coap_session_release()

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 76 of file coap_session.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_session_set_app_data()

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.

Parameters

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

Definition at line 98 of file coap_session.c.

◆ 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 265 of file coap_session.c.

Here is the caller graph for this function:

◆ coap_session_set_type_client()

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 needs to be of type COAP_SESSION_TYPE_SERVER. 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 session to be freed off.

Parameters

session The CoAP session.

Returns: 1 if updated, 0 on failure.

Definition at line 1198 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_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_remote()

◆ coap_session_get_app_data()

◆ coap_session_get_context()

◆ coap_session_get_ifindex()

◆ coap_session_get_proto()

◆ coap_session_get_psk_hint()

◆ 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_mtu()

◆ coap_session_set_type_client()