libcoap 4.3.4

Internal API for handling Sessions. More...

+ Collaboration diagram for Sessions:

Data Structures

struct  coap_addr_hash_t
 Only used for servers for hashing incoming packets. More...
 
struct  coap_session_t
 Abstraction of virtual session that can be attached to coap_context_t (client) or coap_endpoint_t (server). More...
 
struct  coap_endpoint_t
 Abstraction of virtual endpoint that can be attached to coap_context_t. More...
 

Macros

#define COAP_SESSION_REF(s)   ((s)->ref
 
#define COAP_ACK_TIMEOUT(s)   ((s)->ack_timeout)
 
#define COAP_ACK_RANDOM_FACTOR(s)   ((s)->ack_random_factor)
 
#define COAP_MAX_RETRANSMIT(s)   ((s)->max_retransmit)
 
#define COAP_NSTART(s)   ((s)->nstart)
 
#define COAP_DEFAULT_LEISURE(s)   ((s)->default_leisure)
 
#define COAP_PROBING_RATE(s)   ((s)->probing_rate)
 
#define COAP_MAX_PAYLOADS(s)   ((s)->max_payloads)
 
#define COAP_NON_MAX_RETRANSMIT(s)   ((s)->non_max_retransmit)
 
#define COAP_NON_TIMEOUT(s)   ((s)->non_timeout)
 
#define COAP_NON_TIMEOUT_TICKS(s)
 
#define COAP_NON_RECEIVE_TIMEOUT(s)   ((s)->non_receive_timeout)
 
#define COAP_NON_PROBING_WAIT_BASE(s)   ((s)->non_probing_wait_base)
 
#define COAP_NON_PARTIAL_TIMEOUT(s)   ((s)->non_partial_timeout)
 
#define COAP_DEFAULT_LEISURE_TICKS(s)
 The DEFAULT_LEISURE definition for the session (s). More...
 
#define COAP_MAX_TRANSMIT_SPAN(s)
 The MAX_TRANSMIT_SPAN definition for the session (s). More...
 
#define COAP_MAX_TRANSMIT_WAIT(s)
 The MAX_TRANSMIT_WAIT definition for the session (s). More...
 
#define COAP_MAX_TRANSMIT_WAIT_TICKS(s)    (COAP_MAX_TRANSMIT_WAIT(s) * COAP_TICKS_PER_SECOND)
 
#define COAP_PROCESSING_DELAY(s)
 The PROCESSING_DELAY definition for the session (s). More...
 
#define COAP_MAX_RTT(s)    ((2 * COAP_DEFAULT_MAX_LATENCY) + COAP_PROCESSING_DELAY(s))
 The MAX_RTT definition for the session (s). More...
 
#define COAP_EXCHANGE_LIFETIME(s)
 The EXCHANGE_LIFETIME definition for the session (s). More...
 
#define COAP_NON_LIFETIME(s)    (COAP_MAX_TRANSMIT_SPAN(s) + COAP_DEFAULT_MAX_LATENCY)
 The NON_LIFETIME definition for the session (s). More...
 
#define COAP_NON_RECEIVE_TIMEOUT_TICKS(s)
 The NON_RECEIVE_TIMEOUT definition for the session (s). More...
 
#define COAP_NON_PROBING_WAIT(s)
 The NON_PROBING_WAIT definition for the session (s). More...
 
#define COAP_NON_PROBING_WAIT_TICKS(s)
 
#define COAP_NON_PARTIAL_TIMEOUT_TICKS(s)
 The NON_PARTIAL_TIMEOUT definition for the session (s). More...
 
#define COAP_NON_TIMEOUT_RANDOM(s)    coap_get_non_timeout_random(s)
 The NON_TIMEOUT_RANDOM definition for the session (s). More...
 

Typedefs

typedef enum coap_ext_token_check_t coap_ext_token_check_t
 coap_ext_token_check_t values More...
 

Enumerations

enum  COAP_OSCORE_B_2_STEP {
  COAP_OSCORE_B_2_NONE = 0 , COAP_OSCORE_B_2_STEP_1 , COAP_OSCORE_B_2_STEP_2 , COAP_OSCORE_B_2_STEP_3 ,
  COAP_OSCORE_B_2_STEP_4 , COAP_OSCORE_B_2_STEP_5
}
 
enum  coap_ext_token_check_t { COAP_EXT_T_NOT_CHECKED = 0 , COAP_EXT_T_CHECKED , COAP_EXT_T_CHECKING }
 coap_ext_token_check_t values More...
 

Functions

coap_fixed_point_t coap_multi_fixed_fixed (coap_fixed_point_t fp1, coap_fixed_point_t fp2)
 
coap_fixed_point_t coap_multi_fixed_uint (coap_fixed_point_t fp1, uint32_t u2)
 
coap_fixed_point_t coap_add_fixed_fixed (coap_fixed_point_t fp1, coap_fixed_point_t fp2)
 
coap_fixed_point_t coap_add_fixed_uint (coap_fixed_point_t fp1, uint32_t u2)
 
coap_fixed_point_t coap_sub_fixed_uint (coap_fixed_point_t fp1, uint32_t u2)
 
coap_fixed_point_t coap_div_fixed_uint (coap_fixed_point_t fp1, uint32_t u2)
 
coap_fixed_point_t coap_get_non_timeout_random (coap_session_t *session)
 
coap_tick_t coap_get_non_timeout_random_ticks (coap_session_t *session)
 
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...
 
int coap_session_refresh_psk_hint (coap_session_t *session, const coap_bin_const_t *psk_hint)
 Refresh the session's current Identity Hint (PSK). More...
 
int coap_session_refresh_psk_key (coap_session_t *session, const coap_bin_const_t *psk_key)
 Refresh the session's current pre-shared key (PSK). More...
 
int coap_session_refresh_psk_identity (coap_session_t *session, const coap_bin_const_t *psk_identity)
 Refresh the session's current pre-shared identity (PSK). More...
 
coap_session_tcoap_new_server_session (coap_context_t *ctx, coap_endpoint_t *ep)
 Creates a new server session for the specified endpoint. More...
 
void coap_session_establish (coap_session_t *session)
 Layer function interface for layer below session accept/connect being established. 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...
 
ssize_t coap_session_delay_pdu (coap_session_t *session, coap_pdu_t *pdu, coap_queue_t *node)
 
coap_session_tcoap_endpoint_get_session (coap_endpoint_t *endpoint, const 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...
 
size_t coap_session_max_pdu_rcv_size (const coap_session_t *session)
 Get maximum acceptable receive PDU size. More...
 
void coap_session_free (coap_session_t *session)
 
void coap_session_mfree (coap_session_t *session)
 

Detailed Description

Internal API for handling Sessions.

Macro Definition Documentation

◆ COAP_ACK_RANDOM_FACTOR

#define COAP_ACK_RANDOM_FACTOR (   s)    ((s)->ack_random_factor)

Definition at line 390 of file coap_session_internal.h.

◆ COAP_ACK_TIMEOUT

#define COAP_ACK_TIMEOUT (   s)    ((s)->ack_timeout)

Definition at line 389 of file coap_session_internal.h.

◆ COAP_DEFAULT_LEISURE

#define COAP_DEFAULT_LEISURE (   s)    ((s)->default_leisure)

Definition at line 393 of file coap_session_internal.h.

◆ COAP_DEFAULT_LEISURE_TICKS

#define COAP_DEFAULT_LEISURE_TICKS (   s)
Value:
COAP_DEFAULT_LEISURE(s).fractional_part * COAP_TICKS_PER_SECOND / 1000)
#define COAP_TICKS_PER_SECOND
Use ms resolution on POSIX systems.
Definition: coap_time.h:159
#define COAP_DEFAULT_LEISURE(s)

The DEFAULT_LEISURE definition for the session (s).

RFC 7252, Section 4.8 Initial value 5.0 seconds

Definition at line 412 of file coap_session_internal.h.

◆ COAP_EXCHANGE_LIFETIME

#define COAP_EXCHANGE_LIFETIME (   s)
Value:
#define COAP_DEFAULT_MAX_LATENCY
The MAX_LATENCY definition.
Definition: coap_session.h:542
#define COAP_PROCESSING_DELAY(s)
The PROCESSING_DELAY definition for the session (s).
#define COAP_MAX_TRANSMIT_SPAN(s)
The MAX_TRANSMIT_SPAN definition for the session (s).

The EXCHANGE_LIFETIME definition for the session (s).

RFC 7252, Section 4.8.2 Calculation of EXCHANGE_LIFETIME MAX_TRANSMIT_SPAN + (2 * MAX_LATENCY) + PROCESSING_DELAY

Definition at line 469 of file coap_session_internal.h.

◆ COAP_MAX_PAYLOADS

#define COAP_MAX_PAYLOADS (   s)    ((s)->max_payloads)

Definition at line 396 of file coap_session_internal.h.

◆ COAP_MAX_RETRANSMIT

#define COAP_MAX_RETRANSMIT (   s)    ((s)->max_retransmit)

Definition at line 391 of file coap_session_internal.h.

◆ COAP_MAX_RTT

#define COAP_MAX_RTT (   s)     ((2 * COAP_DEFAULT_MAX_LATENCY) + COAP_PROCESSING_DELAY(s))

The MAX_RTT definition for the session (s).

RFC 7252, Section 4.8.2 Calculation of MAX_RTT (2 * MAX_LATENCY) + PROCESSING_DELAY

Definition at line 460 of file coap_session_internal.h.

◆ COAP_MAX_TRANSMIT_SPAN

#define COAP_MAX_TRANSMIT_SPAN (   s)
Value:
(((s)->ack_timeout.integer_part * 1000 + (s)->ack_timeout.fractional_part) * \
((1 << ((s)->max_retransmit)) -1) * \
((s)->ack_random_factor.integer_part * 1000 + \
(s)->ack_random_factor.fractional_part) \
/ 1000000)

The MAX_TRANSMIT_SPAN definition for the session (s).

RFC 7252, Section 4.8.2 Calculation of MAX_TRAMSMIT_SPAN ACK_TIMEOUT * ((2 ** (MAX_RETRANSMIT)) - 1) * ACK_RANDOM_FACTOR

Definition at line 421 of file coap_session_internal.h.

◆ COAP_MAX_TRANSMIT_WAIT

#define COAP_MAX_TRANSMIT_WAIT (   s)
Value:
(((s)->ack_timeout.integer_part * 1000 + (s)->ack_timeout.fractional_part) * \
((1 << ((s)->max_retransmit + 1)) -1) * \
((s)->ack_random_factor.integer_part * 1000 + \
(s)->ack_random_factor.fractional_part) \
/ 1000000)

The MAX_TRANSMIT_WAIT definition for the session (s).

RFC 7252, Section 4.8.2 Calculation of MAX_TRAMSMIT_WAIT ACK_TIMEOUT * ((2 ** (MAX_RETRANSMIT + 1)) - 1) * ACK_RANDOM_FACTOR

Definition at line 434 of file coap_session_internal.h.

◆ COAP_MAX_TRANSMIT_WAIT_TICKS

#define COAP_MAX_TRANSMIT_WAIT_TICKS (   s)     (COAP_MAX_TRANSMIT_WAIT(s) * COAP_TICKS_PER_SECOND)

Definition at line 441 of file coap_session_internal.h.

◆ COAP_NON_LIFETIME

#define COAP_NON_LIFETIME (   s)     (COAP_MAX_TRANSMIT_SPAN(s) + COAP_DEFAULT_MAX_LATENCY)

The NON_LIFETIME definition for the session (s).

RFC 7252, Section 4.8.2 Calculation of NON_LIFETIME MAX_TRANSMIT_SPAN + MAX_LATENCY

Definition at line 479 of file coap_session_internal.h.

◆ COAP_NON_MAX_RETRANSMIT

#define COAP_NON_MAX_RETRANSMIT (   s)    ((s)->non_max_retransmit)

Definition at line 397 of file coap_session_internal.h.

◆ COAP_NON_PARTIAL_TIMEOUT

#define COAP_NON_PARTIAL_TIMEOUT (   s)    ((s)->non_partial_timeout)

Definition at line 404 of file coap_session_internal.h.

◆ COAP_NON_PARTIAL_TIMEOUT_TICKS

#define COAP_NON_PARTIAL_TIMEOUT_TICKS (   s)
Value:
COAP_NON_PARTIAL_TIMEOUT(s).fractional_part * COAP_TICKS_PER_SECOND / 1000)
#define COAP_NON_PARTIAL_TIMEOUT(s)

The NON_PARTIAL_TIMEOUT definition for the session (s).

RFC9177 Section 6.2 Initial value EXCHANGE_LIFETIME (247 seconds)

Definition at line 514 of file coap_session_internal.h.

◆ COAP_NON_PROBING_WAIT

#define COAP_NON_PROBING_WAIT (   s)
Value:
#define COAP_NON_PROBING_WAIT_BASE(s)
#define COAP_NON_TIMEOUT_RANDOM(s)
The NON_TIMEOUT_RANDOM definition for the session (s).
coap_fixed_point_t coap_add_fixed_fixed(coap_fixed_point_t fp1, coap_fixed_point_t fp2)
Definition: coap_session.c:50

The NON_PROBING_WAIT definition for the session (s).

RFC9177 Section 6.2 NON_PROBING_WAIT = NON_TIMEOUT * ((2 ** NON_MAX_RETRANSMIT) - 1) * ACK_RANDOM_FACTOR + (2 * MAX_LATENCY) + NON_TIMEOUT_RANDOM Default is 247-248 seconds

Definition at line 500 of file coap_session_internal.h.

◆ COAP_NON_PROBING_WAIT_BASE

#define COAP_NON_PROBING_WAIT_BASE (   s)    ((s)->non_probing_wait_base)

Definition at line 403 of file coap_session_internal.h.

◆ COAP_NON_PROBING_WAIT_TICKS

#define COAP_NON_PROBING_WAIT_TICKS (   s)
Value:
COAP_NON_PROBING_WAIT(s).fractional_part * COAP_TICKS_PER_SECOND / 1000)
#define COAP_NON_PROBING_WAIT(s)
The NON_PROBING_WAIT definition for the session (s).

Definition at line 504 of file coap_session_internal.h.

◆ COAP_NON_RECEIVE_TIMEOUT

#define COAP_NON_RECEIVE_TIMEOUT (   s)    ((s)->non_receive_timeout)

Definition at line 402 of file coap_session_internal.h.

◆ COAP_NON_RECEIVE_TIMEOUT_TICKS

#define COAP_NON_RECEIVE_TIMEOUT_TICKS (   s)
Value:
( \
COAP_NON_RECEIVE_TIMEOUT(s).integer_part * COAP_TICKS_PER_SECOND + \
COAP_NON_RECEIVE_TIMEOUT(s).fractional_part * COAP_TICKS_PER_SECOND / 1000)

The NON_RECEIVE_TIMEOUT definition for the session (s).

RFC9177 Section 6.2 2 * NON_TIMEOUT

Definition at line 488 of file coap_session_internal.h.

◆ COAP_NON_TIMEOUT

#define COAP_NON_TIMEOUT (   s)    ((s)->non_timeout)

Definition at line 398 of file coap_session_internal.h.

◆ COAP_NON_TIMEOUT_RANDOM

#define COAP_NON_TIMEOUT_RANDOM (   s)     coap_get_non_timeout_random(s)

The NON_TIMEOUT_RANDOM definition for the session (s).

RFC9177 Section 6.2 Default is 2-3 seconds

Definition at line 524 of file coap_session_internal.h.

◆ COAP_NON_TIMEOUT_TICKS

#define COAP_NON_TIMEOUT_TICKS (   s)
Value:
(COAP_NON_TIMEOUT(s).integer_part * COAP_TICKS_PER_SECOND + \
COAP_NON_TIMEOUT(s).fractional_part * COAP_TICKS_PER_SECOND / 1000)
#define COAP_NON_TIMEOUT(s)

Definition at line 399 of file coap_session_internal.h.

◆ COAP_NSTART

#define COAP_NSTART (   s)    ((s)->nstart)

Definition at line 392 of file coap_session_internal.h.

◆ COAP_PROBING_RATE

#define COAP_PROBING_RATE (   s)    ((s)->probing_rate)

Definition at line 394 of file coap_session_internal.h.

◆ COAP_PROCESSING_DELAY

#define COAP_PROCESSING_DELAY (   s)
Value:
(((s)->ack_timeout.integer_part * 1000 + (s)->ack_timeout.fractional_part + \
500) / 1000)

The PROCESSING_DELAY definition for the session (s).

RFC 7252, Section 4.8.2 Calculation of PROCESSING_DELAY PROCESSING_DELAY set to ACK_TIMEOUT

Definition at line 450 of file coap_session_internal.h.

◆ COAP_SESSION_REF

#define COAP_SESSION_REF (   s)    ((s)->ref

Definition at line 386 of file coap_session_internal.h.

Typedef Documentation

◆ coap_ext_token_check_t

coap_ext_token_check_t values

Enumeration Type Documentation

◆ coap_ext_token_check_t

coap_ext_token_check_t values

Enumerator
COAP_EXT_T_NOT_CHECKED 

Not checked.

COAP_EXT_T_CHECKED 

Token size valid.

COAP_EXT_T_CHECKING 

Token size check request sent.

Definition at line 58 of file coap_session_internal.h.

◆ COAP_OSCORE_B_2_STEP

Enumerator
COAP_OSCORE_B_2_NONE 
COAP_OSCORE_B_2_STEP_1 
COAP_OSCORE_B_2_STEP_2 
COAP_OSCORE_B_2_STEP_3 
COAP_OSCORE_B_2_STEP_4 
COAP_OSCORE_B_2_STEP_5 

Definition at line 46 of file coap_session_internal.h.

Function Documentation

◆ coap_add_fixed_fixed()

coap_fixed_point_t coap_add_fixed_fixed ( coap_fixed_point_t  fp1,
coap_fixed_point_t  fp2 
)

Definition at line 50 of file coap_session.c.

◆ coap_add_fixed_uint()

coap_fixed_point_t coap_add_fixed_uint ( coap_fixed_point_t  fp1,
uint32_t  u2 
)

Definition at line 60 of file coap_session.c.

◆ coap_div_fixed_uint()

coap_fixed_point_t coap_div_fixed_uint ( coap_fixed_point_t  fp1,
uint32_t  u2 
)

Definition at line 76 of file coap_session.c.

◆ coap_endpoint_get_session()

coap_session_t * coap_endpoint_get_session ( coap_endpoint_t endpoint,
const 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 or NULL if error.

◆ coap_get_non_timeout_random()

coap_fixed_point_t coap_get_non_timeout_random ( coap_session_t session)

◆ coap_get_non_timeout_random_ticks()

coap_tick_t coap_get_non_timeout_random_ticks ( coap_session_t session)
+ Here is the caller graph for this function:

◆ coap_multi_fixed_fixed()

coap_fixed_point_t coap_multi_fixed_fixed ( coap_fixed_point_t  fp1,
coap_fixed_point_t  fp2 
)

Definition at line 30 of file coap_session.c.

◆ coap_multi_fixed_uint()

coap_fixed_point_t coap_multi_fixed_uint ( coap_fixed_point_t  fp1,
uint32_t  u2 
)

Definition at line 40 of file coap_session.c.

◆ coap_new_server_session()

coap_session_t * coap_new_server_session ( coap_context_t ctx,
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 add to unused queue.

◆ 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 759 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,
coap_queue_t node 
)

Definition at line 650 of file coap_session.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_session_establish()

void coap_session_establish ( coap_session_t session)

Layer function interface for layer below session accept/connect being established.

This function initiates a CSM request for reliable protocols, or coap_session_connect() for un-reliable protocols.

Parameters
sessionSession that the lower layer accept/connect was done on.

Definition at line 1270 of file coap_session.c.

+ Here is the call graph for this function:

◆ coap_session_free()

void coap_session_free ( coap_session_t session)

Definition at line 545 of file coap_session.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_session_max_pdu_rcv_size()

size_t coap_session_max_pdu_rcv_size ( const coap_session_t session)

Get maximum acceptable receive PDU size.

Parameters
sessionThe CoAP session.
Returns
maximum PDU size, not including header (but including token).

Definition at line 598 of file coap_session.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_session_mfree()

void coap_session_mfree ( coap_session_t session)

Definition at line 464 of file coap_session.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_session_refresh_psk_hint()

int coap_session_refresh_psk_hint ( coap_session_t session,
const coap_bin_const_t psk_hint 
)

Refresh the session's current Identity Hint (PSK).

Note: A copy of psk_hint is maintained in the session by libcoap.

Parameters
sessionThe current coap_session_t object.
psk_hintIf NULL, the Identity Hint will revert to the initial Identity Hint used at session setup.
Returns
1 if successful, else 0.

Definition at line 1376 of file coap_session.c.

+ Here is the call graph for this function:

◆ coap_session_refresh_psk_identity()

int coap_session_refresh_psk_identity ( coap_session_t session,
const coap_bin_const_t psk_identity 
)

Refresh the session's current pre-shared identity (PSK).

Note: A copy of psk_identity is maintained in the session by libcoap.

Parameters
sessionThe current coap_session_t object.
psk_identityIf NULL, the pre-shared identity will revert to the initial pre-shared key used as session setup.
Returns
1 if successful, else 0.

Definition at line 1433 of file coap_session.c.

+ Here is the call graph for this function:

◆ coap_session_refresh_psk_key()

int coap_session_refresh_psk_key ( coap_session_t session,
const coap_bin_const_t psk_key 
)

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

Note: A copy of psk_key is maintained in the session by libcoap.

Parameters
sessionThe current coap_session_t object.
psk_keyIf NULL, the pre-shared key will revert to the initial pre-shared key used at session setup.
Returns
1 if successful, else 0.

Definition at line 1405 of file coap_session.c.

+ Here is the call 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 691 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 784 of file coap_net.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_sub_fixed_uint()

coap_fixed_point_t coap_sub_fixed_uint ( coap_fixed_point_t  fp1,
uint32_t  u2 
)

Definition at line 68 of file coap_session.c.