libcoap  4.3.0rc2
Sessions

API functions for CoAP Sessions. More...

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)   ((p)==COAP_PROTO_TCP || (p)==COAP_PROTO_TLS)
 

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 from the session. More...
 
const coap_address_tcoap_session_get_addr_local (const coap_session_t *session)
 Get the local IP address 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_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 *ep)
 

Detailed Description

API functions for CoAP Sessions.

Macro Definition Documentation

◆ COAP_PROTO_NOT_RELIABLE

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

Definition at line 33 of file coap_session.h.

◆ COAP_PROTO_RELIABLE

#define COAP_PROTO_RELIABLE (   p)    ((p)==COAP_PROTO_TCP || (p)==COAP_PROTO_TLS)

Definition at line 34 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 50 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 39 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

Definition at line 1320 of file coap_session.c.

◆ coap_free_endpoint()

void coap_free_endpoint ( coap_endpoint_t ep)

Definition at line 1325 of file coap_session.c.

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

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

Definition at line 1068 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 ( 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 914 of file coap_session.c.

+ Here is the call graph for this function:

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

Definition at line 941 of file coap_session.c.

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

◆ 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

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

This cleans up any outstanding / queued transmissions, observations etc..

Parameters
sessionThe CoAP session.
reasonThe reason why the session was disconnected.

Definition at line 454 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 from the session.

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

Definition at line 1171 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 from the session.

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

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

◆ 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 1178 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 1215 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 1185 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.

Definition at line 1055 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 1062 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 1209 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 1221 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 1192 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 1147 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 242 of file coap_session.c.

+ 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 1152 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 68 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 74 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 96 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 263 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.

Definition at line 1199 of file coap_session.c.

+ Here is the call graph for this function: