libcoap  4.2.0
coap_session.h File Reference
#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:

Go to the source code of 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_tcoap_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_tcoap_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_tcoap_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_tcoap_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_tcoap_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_tcoap_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_tcoap_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_tcoap_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_tcoap_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

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

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

Definition at line 46 of file coap_session.h.

◆ coap_session_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
endpointActive endpoint the packet was received on.
packetReceived packet.
nowThe 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
endpointThe CoAP endpoint.
mtumaximum 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
ctxThe CoAP context.
local_ifAddress 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.
serverThe server's address. If the port number is zero, the default port for the protocol will be used.
protoProtocol.
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
ctxThe CoAP context.
local_ifAddress 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.
serverThe server's address. If the port number is zero, the default port for the protocol will be used.
protoCoAP Protocol.
setup_dataPKI 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
ctxThe CoAP context.
local_ifAddress 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.
serverThe server's address. If the port number is zero, the default port for the protocol will be used.
protoProtocol.
identityPSK client identity
keyPSK shared key
key_lenPSK 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
contextThe coap context that will own the new endpoint
listen_addrAddress 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.
protoProtocol 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
ctxThe CoAP context.
epAn 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
sessionThe 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
sessionThe CoAP session.
reasonThe 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
sessionThe 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
sessionThe 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
sessionThe 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
sessionThe 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
sessionThe 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
sessionThe 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
sessionSession to send data on.
dataThe data to send.
datalenThe 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
sessionThe 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
sessionSession to send pdu on.
pduThe 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
sessionThe 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
sessionThe CoAP session.
valueThe 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
sessionThe CoAP session.
valueThe 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
sessionThe CoAP session.
valueThe 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
sessionThe CoAP session.
mtumaximum 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
sessionSession to send data on.
dataThe data to send.
datalenThe 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: