libcoap 4.3.3

API for CoAP Session access. More...

+ Collaboration diagram for Sessions:

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)
 

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_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_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_tcoap_session_get_addr_remote (const coap_session_t *session)
 Get the remote IP address and port from the session. More...
 
const coap_address_tcoap_session_get_addr_mcast (const coap_session_t *session)
 Get the remote multicast IP address and port from the session if the original target IP was multicast. More...
 
const coap_address_tcoap_session_get_addr_local (const coap_session_t *session)
 Get the local IP address and port 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_tcoap_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_tcoap_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_tcoap_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_tcoap_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_tcoap_session_get_psk_hint (const coap_session_t *session)
 Get the server session's current Identity Hint (PSK). More...
 
const coap_bin_const_tcoap_session_get_psk_identity (const coap_session_t *session)
 Get the server session's current PSK identity (PSK). More...
 
const coap_bin_const_tcoap_session_get_psk_key (const coap_session_t *session)
 Get the session's current pre-shared key (PSK). More...
 
coap_session_tcoap_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_tcoap_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 *endpoint)
 Release an endpoint and all the structures associated with it. More...
 
coap_session_tcoap_session_get_by_peer (const coap_context_t *context, const coap_address_t *remote_addr, int ifindex)
 Get the session associated with the specified remote_addr and index. More...
 

Detailed Description

API for CoAP Session access.

Macro Definition Documentation

◆ COAP_PROTO_NOT_RELIABLE

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

Definition at line 36 of file coap_session.h.

◆ COAP_PROTO_RELIABLE

#define COAP_PROTO_RELIABLE (   p)
Value:
((p)==COAP_PROTO_TCP || (p)==COAP_PROTO_TLS || \
@ COAP_PROTO_WS
Definition: coap_pdu.h:310
@ COAP_PROTO_TLS
Definition: coap_pdu.h:309
@ COAP_PROTO_WSS
Definition: coap_pdu.h:311
@ COAP_PROTO_TCP
Definition: coap_pdu.h:308

Definition at line 37 of file coap_session.h.

Typedef Documentation

◆ 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

coap_session_state_t values

◆ coap_session_type_t

coap_session_type_t values

Enumeration Type Documentation

◆ 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 54 of file coap_session.h.

◆ 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 43 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
endpointThe CoAP endpoint.
mtumaximum message size

◆ coap_free_endpoint()

void coap_free_endpoint ( coap_endpoint_t endpoint)

Release an endpoint and all the structures associated with it.

Parameters
endpointThe endpoint to release.
+ 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
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.

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

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

Deprecated:
Use coap_new_client_session_psk2() instead.
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.

◆ 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
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_dataPSK parameters.
Returns
A new CoAP session or NULL if failed. Call coap_session_release() to free.

◆ 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
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,
Returns
The new endpoint or NULL on failure.
+ 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
sessionThe CoAP session.
reasonThe reason why the session was disconnected.

Definition at line 848 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 and port from the session.

Parameters
sessionThe CoAP session.
Returns
The session's local address or NULL on failure.

Definition at line 1605 of file coap_session.c.

◆ coap_session_get_addr_mcast()

const coap_address_t * coap_session_get_addr_mcast ( const coap_session_t session)

Get the remote multicast IP address and port from the session if the original target IP was multicast.

Note: This is only available for a client.

Parameters
sessionThe CoAP session.
Returns
The session's remote multicast address or NULL on failure or if this is not a multicast session.

Definition at line 1612 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 and port from the session.

Note: For clients, this can be the responding IP address for a multicast request before the next coap_send() is called when the multicast address is restored.

Parameters
sessionThe CoAP session.
Returns
The session's remote address or NULL on failure.

Definition at line 1598 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
sessionThe CoAP session.
Returns
Pointer to the stored data or NULL.

Definition at line 382 of file coap_session.c.

◆ coap_session_get_by_peer()

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

Get the session associated with the specified remote_addr and index.

Parameters
contextThe context to search.
remote_addrThe remote (peer) address to search for.
ifindexThe Interface index that is used to access remote_addr.
Returns
The found session or NULL if not found.

Definition at line 1849 of file coap_session.c.

+ Here is the call graph for this function:

◆ coap_session_get_context()

coap_context_t * coap_session_get_context ( const coap_session_t session)

Get the session context.

Parameters
sessionThe CoAP session.
Returns
The session's context

Definition at line 1624 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
sessionThe CoAP session.
Returns
The session's if index, or -1 on error.

Definition at line 1668 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
sessionThe CoAP session.
Returns
The session's protocol type

Definition at line 1631 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
sessionThe current coap_session_t object.
Returns
hint if successful, else NULL.

◆ coap_session_get_psk_identity()

const coap_bin_const_t * coap_session_get_psk_identity ( const coap_session_t session)

Get the server session's current PSK identity (PSK).

Parameters
sessionThe current coap_session_t object.
Returns
PSK identity if successful, else NULL.

Definition at line 1471 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
sessionThe current coap_session_t object.
Returns
psk_key if successful, else NULL.

Definition at line 1483 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
sessionThe CoAP session.
Returns
The session's state

Definition at line 1661 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
sessionThe CoAP session.
tls_libUpdated with the library type.
Returns
The session TLS ptr or NULL if not set up

Definition at line 1675 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
sessionThe CoAP session.
Returns
The session's type

Definition at line 1638 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
sessionThe current coap_session_t object.
lengthThe length of the token (0 - 8 bytes).
tokenThe token data.

Definition at line 1577 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
sessionThe CoAP session.
Returns
maximum PDU size, not including header (but including token).

Definition at line 608 of file coap_session.c.

+ Here is the call graph for this function:
+ 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
sessionThe current coap_session_t object.
lengthUpdated with the length of the new token.
tokenUpdated with the new token data (must be 8 bytes long).

Definition at line 1583 of file coap_session.c.

+ Here is the call 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 348 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 354 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
sessionThe CoAP session.
dataThe pointer to the data to store.

Definition at line 376 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
sessionThe CoAP session.
mtumaximum message size

Definition at line 635 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
sessionThe CoAP session.
Returns
1 if updated, 0 on failure.