libcoap 4.3.1

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

Functions

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...
 
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...
 
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 336 of file coap_session_internal.h.

◆ COAP_ACK_TIMEOUT

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

Definition at line 335 of file coap_session_internal.h.

◆ COAP_DEFAULT_LEISURE

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

Definition at line 339 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:142
#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 348 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:463
#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 405 of file coap_session_internal.h.

◆ COAP_MAX_RETRANSMIT

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

Definition at line 337 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 396 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 357 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 370 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 377 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 415 of file coap_session_internal.h.

◆ COAP_NSTART

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

Definition at line 338 of file coap_session_internal.h.

◆ COAP_PROBING_RATE

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

Definition at line 340 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 386 of file coap_session_internal.h.

◆ COAP_SESSION_REF

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

Definition at line 332 of file coap_session_internal.h.

Function Documentation

◆ 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_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 534 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 438 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 302 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 351 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 228 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 1185 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 1244 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 1215 of file coap_session.c.

+ Here is the call 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 401 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 479 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 770 of file net.c.

+ Here is the call graph for this function:
+ 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 424 of file coap_session.c.

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