#include "coap_io.h"
#include "coap_time.h"
#include "pdu.h"

Include dependency graph for coap_session.h:

This graph shows which files directly or indirectly include this file:

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

struct	coap_session_t

struct	coap_endpoint_t
	Abstraction of virtual endpoint that can be attached to coap_context_t. More...

Macros
#define	COAP_DEFAULT_SESSION_TIMEOUT 300

#define	COAP_PARTIAL_SESSION_TIMEOUT_TICKS (30 * COAP_TICKS_PER_SECOND)

#define	COAP_DEFAULT_MAX_HANDSHAKE_SESSIONS 100

#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)

#define	COAP_SESSION_TYPE_CLIENT 1
	coap_session_type_t values More...

#define	COAP_SESSION_TYPE_SERVER 2
	server-side More...

#define	COAP_SESSION_TYPE_HELLO 3
	server-side ephemeral session for responding to a client hello More...

#define	COAP_SESSION_STATE_NONE 0
	coap_session_state_t values More...

#define	COAP_SESSION_STATE_CONNECTING 1

#define	COAP_SESSION_STATE_HANDSHAKE 2

#define	COAP_SESSION_STATE_CSM 3

#define	COAP_SESSION_STATE_ESTABLISHED 4

#define	COAP_DEFAULT_ACK_TIMEOUT ((coap_fixed_point_t){2,0})
	Number of seconds when to expect an ACK or a response to an outstanding CON message. More...

#define	COAP_DEFAULT_ACK_RANDOM_FACTOR ((coap_fixed_point_t){1,500})
	A factor that is used to randomize the wait time before a message is retransmitted to prevent synchronization effects. More...

#define	COAP_DEFAULT_MAX_RETRANSMIT 4
	Number of message retransmissions before message sending is stopped RFC 7252, Section 4.8 Default value of MAX_RETRANSMIT is 4. More...

#define	COAP_DEFAULT_NSTART 1
	The number of simultaneous outstanding interactions that a client maintains to a given server. More...

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 uint8_t	coap_session_type_t

typedef uint8_t	coap_session_state_t

typedef struct coap_session_t	coap_session_t

typedef struct coap_endpoint_t	coap_endpoint_t
	Abstraction of virtual endpoint that can be attached to coap_context_t. 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_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...

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

void	coap_session_send_csm (coap_session_t *session)
	Notify session transport has just connected and CSM exchange can now start. More...

void	coap_session_connected (coap_session_t *session)
	Notify session that it has just connected or reconnected. 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 (struct 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 (struct 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_pki (struct coap_context_t ctx, const coap_address_t local_if, const coap_address_t server, coap_proto_t proto, struct coap_dtls_pki_t setup_data)
	Creates a new client session to the designated server with PKI credentials. More...

coap_session_t *	coap_new_server_session (struct coap_context_t ctx, struct coap_endpoint_t ep)
	Creates a new server session for the specified endpoint. More...

ssize_t	coap_session_send (coap_session_t session, const uint8_t data, size_t datalen)
	Function interface for datagram data transmission. More...

ssize_t	coap_session_write (coap_session_t session, const uint8_t data, size_t datalen)
	Function interface for stream data transmission. More...

ssize_t	coap_session_send_pdu (coap_session_t session, coap_pdu_t pdu)
	Send a pdu according to the session's protocol. More...

const char *	coap_session_str (const coap_session_t *session)
	Get session description. More...

ssize_t	coap_session_delay_pdu (coap_session_t session, coap_pdu_t pdu, struct coap_queue_t *node)

coap_endpoint_t *	coap_new_endpoint (struct 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)

const char *	coap_endpoint_str (const coap_endpoint_t *endpoint)
	Get endpoint description. More...

coap_session_t *	coap_endpoint_get_session (coap_endpoint_t endpoint, const struct coap_packet_t packet, coap_tick_t now)
	Lookup the server session for the packet received on an endpoint, or create a new one. More...

coap_session_t *	coap_endpoint_new_dtls_session (coap_endpoint_t endpoint, const struct coap_packet_t packet, coap_tick_t now)
	Create a new DTLS session for the `endpoint`. More...

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

void	coap_session_free (coap_session_t *session)

void	coap_session_mfree (coap_session_t *session)

void	coap_session_set_max_retransmit (coap_session_t *session, unsigned int value)
	Set the CoAP maximum retransmit count before failure. More...

void	coap_session_set_ack_timeout (coap_session_t *session, coap_fixed_point_t value)
	Set the CoAP initial ack response timeout before the next re-transmit. More...

void	coap_session_set_ack_random_factor (coap_session_t *session, coap_fixed_point_t value)
	Set the CoAP ack randomize factor. More...

unsigned int	coap_session_get_max_transmit (coap_session_t *session)
	Get the CoAP maximum retransmit before failure. More...

coap_fixed_point_t	coap_session_get_ack_timeout (coap_session_t *session)
	Get the CoAP initial ack response timeout before the next re-transmit. More...

coap_fixed_point_t	coap_session_get_ack_random_factor (coap_session_t *session)
	Get the CoAP ack randomize factor. More...

coap_tid_t	coap_session_send_ping (coap_session_t *session)
	Send a ping message for the session. More...

Macro Definition Documentation

◆ COAP_DEFAULT_MAX_HANDSHAKE_SESSIONS

#define COAP_DEFAULT_MAX_HANDSHAKE_SESSIONS 100

Definition at line 33 of file coap_session.h.

◆ COAP_DEFAULT_SESSION_TIMEOUT

#define COAP_DEFAULT_SESSION_TIMEOUT 300

Definition at line 31 of file coap_session.h.

◆ COAP_PARTIAL_SESSION_TIMEOUT_TICKS

#define COAP_PARTIAL_SESSION_TIMEOUT_TICKS (30 * COAP_TICKS_PER_SECOND)

Definition at line 32 of file coap_session.h.

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

◆ COAP_SESSION_STATE_CONNECTING

#define COAP_SESSION_STATE_CONNECTING 1

Definition at line 51 of file coap_session.h.

◆ COAP_SESSION_STATE_CSM

#define COAP_SESSION_STATE_CSM 3

Definition at line 53 of file coap_session.h.

◆ COAP_SESSION_STATE_ESTABLISHED

#define COAP_SESSION_STATE_ESTABLISHED 4

Definition at line 54 of file coap_session.h.

◆ COAP_SESSION_STATE_HANDSHAKE

#define COAP_SESSION_STATE_HANDSHAKE 2

Definition at line 52 of file coap_session.h.

◆ COAP_SESSION_STATE_NONE

#define COAP_SESSION_STATE_NONE 0

coap_session_state_t values

Definition at line 50 of file coap_session.h.

◆ COAP_SESSION_TYPE_CLIENT

#define COAP_SESSION_TYPE_CLIENT 1

coap_session_type_t values

client-side

Definition at line 42 of file coap_session.h.

◆ COAP_SESSION_TYPE_HELLO

#define COAP_SESSION_TYPE_HELLO 3

server-side ephemeral session for responding to a client hello

Definition at line 44 of file coap_session.h.

◆ COAP_SESSION_TYPE_SERVER

#define COAP_SESSION_TYPE_SERVER 2

server-side

Definition at line 43 of file coap_session.h.

Typedef Documentation

◆ coap_endpoint_t

typedef struct coap_endpoint_t coap_endpoint_t

Abstraction of virtual endpoint that can be attached to coap_context_t.

The tuple (handle, addr) must uniquely identify this endpoint.

◆ 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 uint8_t coap_session_state_t

Definition at line 46 of file coap_session.h.

◆ coap_session_t

typedef struct coap_session_t coap_session_t

◆ coap_session_type_t

typedef uint8_t coap_session_type_t

Definition at line 38 of file coap_session.h.

Function Documentation

◆ coap_endpoint_get_session()

coap_session_t* coap_endpoint_get_session	(	coap_endpoint_t *	endpoint,
		const struct coap_packet_t *	packet,
		coap_tick_t	now
	)

Lookup the server session for the packet received on an endpoint, or create a new one.

Parameters

endpoint	Active endpoint the packet was received on.
packet	Received packet.
now	The current time in ticks.

Returns: The CoAP session.

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

◆ coap_free_endpoint()

void coap_free_endpoint ( coap_endpoint_t * ep )

Definition at line 901 of file coap_session.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_new_client_session()

coap_session_t* coap_new_client_session	(	struct 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 665 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	(	struct coap_context_t *	ctx,
		const coap_address_t *	local_if,
		const coap_address_t *	server,
		coap_proto_t	proto,
		struct 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 740 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	(	struct 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 680 of file coap_session.c.

Here is the call graph for this function:

◆ coap_new_endpoint()

coap_endpoint_t* coap_new_endpoint	(	struct 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 810 of file coap_session.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_new_server_session()

coap_session_t* coap_new_server_session	(	struct coap_context_t *	ctx,
		struct coap_endpoint_t *	ep
	)

Creates a new server session for the specified endpoint.

Parameters

ctx	The CoAP context.
ep	An endpoint where an incoming connection request is pending.

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

Definition at line 780 of file coap_session.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_session_connected()

void coap_session_connected ( coap_session_t * session )

Notify session that it has just connected or reconnected.

Parameters

session The CoAP session.

Definition at line 326 of file coap_session.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_session_delay_pdu()

ssize_t coap_session_delay_pdu	(	coap_session_t *	session,
		coap_pdu_t *	pdu,
		struct coap_queue_t *	node
	)

Definition at line 253 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.

Parameters

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

Definition at line 383 of file coap_session.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_session_free()

void coap_session_free ( coap_session_t * session )

Definition at line 170 of file coap_session.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_session_get_ack_random_factor()

coap_fixed_point_t coap_session_get_ack_random_factor ( coap_session_t * session )

Get the CoAP ack randomize factor.

A factor that is used to randomize the wait time before a message is retransmitted to prevent synchronization effects.

Parameters

session The CoAP session.

Returns: Current ack randomize value

Definition at line 66 of file coap_session.c.

◆ coap_session_get_ack_timeout()

coap_fixed_point_t coap_session_get_ack_timeout ( coap_session_t * session )

Get the CoAP initial ack response timeout before the next re-transmit.

Number of seconds when to expect an ACK or a response to an outstanding CON message.

Parameters

session The CoAP session.

Returns: Current ack response timeout value

Definition at line 61 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.

Definition at line 94 of file coap_session.c.

◆ coap_session_get_by_peer()

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

◆ coap_session_get_max_transmit()

unsigned int coap_session_get_max_transmit ( coap_session_t * session )

Get the CoAP maximum retransmit before failure.

Number of message retransmissions before message sending is stopped

Parameters

session The CoAP session.

Returns: Current maximum retransmit value

Definition at line 56 of file coap_session.c.

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

Here is the caller graph for this function:

◆ coap_session_mfree()

void coap_session_mfree ( coap_session_t * session )

Definition at line 147 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 71 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 77 of file coap_session.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_session_send()

ssize_t coap_session_send	(	coap_session_t *	session,
		const uint8_t *	data,
		size_t	datalen
	)

Function interface for datagram data transmission.

This function returns the number of bytes that have been transmitted, or a value less than zero on error.

Parameters

session	Session to send data on.
data	The data to send.
datalen	The actual length of `data`.

Returns: The number of bytes written on success, or a value less than zero on error.

Definition at line 218 of file coap_session.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_session_send_csm()

void coap_session_send_csm ( coap_session_t * session )

Notify session transport has just connected and CSM exchange can now start.

Parameters

session The CoAP session.

Definition at line 290 of file coap_session.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_session_send_pdu()

ssize_t coap_session_send_pdu	(	coap_session_t *	session,
		coap_pdu_t *	pdu
	)

Send a pdu according to the session's protocol.

This function returns the number of bytes that have been transmitted, or a value less than zero on error.

Parameters

session	Session to send pdu on.
pdu	The pdu to send.

Returns: The number of bytes written on success, or a value less than zero on error.

Definition at line 627 of file net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_session_send_ping()

coap_tid_t coap_session_send_ping ( coap_session_t * session )

Send a ping message for the session.

Parameters

session The CoAP session.

Returns: COAP_INVALID_TID if there is an error

Definition at line 316 of file coap_session.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_session_set_ack_random_factor()

void coap_session_set_ack_random_factor	(	coap_session_t *	session,
		coap_fixed_point_t	value
	)

Set the CoAP ack randomize factor.

A factor that is used to randomize the wait time before a message is retransmitted to prevent synchronization effects.

Parameters

session	The CoAP session.
value	The value to set to. The default is 1.5 and should not normally get changed.

Definition at line 45 of file coap_session.c.

Here is the call graph for this function:

◆ coap_session_set_ack_timeout()

void coap_session_set_ack_timeout	(	coap_session_t *	session,
		coap_fixed_point_t	value
	)

Set the CoAP initial ack response timeout before the next re-transmit.

Number of seconds when to expect an ACK or a response to an outstanding CON message.

Parameters

session	The CoAP session.
value	The value to set to. The default is 2 and should not normally get changed.

Definition at line 35 of file coap_session.c.

Here is the call 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.

Definition at line 88 of file coap_session.c.

◆ coap_session_set_max_retransmit()

void coap_session_set_max_retransmit	(	coap_session_t *	session,
		unsigned int	value
	)

Set the CoAP maximum retransmit count before failure.

Number of message retransmissions before message sending is stopped

Parameters

session	The CoAP session.
value	The value to set to. The default is 4 and should not normally get changed.

Definition at line 26 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 206 of file coap_session.c.

Here is the caller graph for this function:

◆ coap_session_write()

ssize_t coap_session_write	(	coap_session_t *	session,
		const uint8_t *	data,
		size_t	datalen
	)

Function interface for stream data transmission.

This function returns the number of bytes that have been transmitted, or a value less than zero on error. The number of bytes written may be less than datalen because of congestion control.

Parameters

session	Session to send data on.
data	The data to send.
datalen	The actual length of `data`.

Returns: The number of bytes written on success, or a value less than zero on error.

Definition at line 239 of file coap_session.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ COAP_DEFAULT_MAX_HANDSHAKE_SESSIONS

◆ COAP_DEFAULT_SESSION_TIMEOUT

◆ COAP_PARTIAL_SESSION_TIMEOUT_TICKS

◆ COAP_PROTO_NOT_RELIABLE

◆ COAP_PROTO_RELIABLE

◆ COAP_SESSION_STATE_CONNECTING

◆ COAP_SESSION_STATE_CSM

◆ COAP_SESSION_STATE_ESTABLISHED

◆ COAP_SESSION_STATE_HANDSHAKE

◆ COAP_SESSION_STATE_NONE

◆ COAP_SESSION_TYPE_CLIENT

◆ COAP_SESSION_TYPE_HELLO

◆ COAP_SESSION_TYPE_SERVER

Typedef Documentation

◆ coap_endpoint_t

◆ coap_fixed_point_t

◆ coap_session_state_t

◆ coap_session_t

◆ coap_session_type_t

Function Documentation

◆ coap_endpoint_get_session()

◆ coap_endpoint_set_default_mtu()

◆ coap_free_endpoint()

◆ coap_new_client_session()

◆ coap_new_client_session_pki()

◆ coap_new_client_session_psk()

◆ coap_new_endpoint()

◆ coap_new_server_session()

◆ coap_session_connected()

◆ coap_session_delay_pdu()

◆ coap_session_disconnected()

◆ coap_session_free()

◆ coap_session_get_ack_random_factor()

◆ coap_session_get_ack_timeout()

◆ coap_session_get_app_data()

◆ coap_session_get_by_peer()

◆ coap_session_get_max_transmit()

◆ coap_session_max_pdu_size()

◆ coap_session_mfree()

◆ coap_session_reference()

◆ coap_session_release()

◆ coap_session_send()

◆ coap_session_send_csm()

◆ coap_session_send_pdu()

◆ coap_session_send_ping()

◆ coap_session_set_ack_random_factor()

◆ coap_session_set_ack_timeout()

◆ coap_session_set_app_data()

◆ coap_session_set_max_retransmit()

◆ coap_session_set_mtu()

◆ coap_session_write()