libcoap 4.3.2rc2

Data Structures | Macros | Typedefs | Enumerations | Functions
Sessions
Application API

API for CoAP Session access. 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)

## 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_t * | coap_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_t * | coap_session_get_addr_remote (const coap_session_t *session)
| Get the remote IP address and port from the session. More...
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. More...
const coap_address_t * | coap_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_t * | coap_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_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. More...
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. More...
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. More...
const coap_bin_const_t * | coap_session_get_psk_hint (const coap_session_t *session)
| Get the server session's current Identity Hint (PSK). More...
const coap_bin_const_t * | coap_session_get_psk_identity (const coap_session_t *session)
| Get the server session's current PSK identity (PSK). More...
const coap_bin_const_t * | coap_session_get_psk_key (const coap_session_t *session)
| Get the session's current pre-shared key (PSK). More...
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. 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_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. 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_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`. 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 || \
(p)==COAP_PROTO_WS || (p)==COAP_PROTO_WSS)
COAP_PROTO_WS
@ COAP_PROTO_WS
Definition: coap_pdu.h:310
COAP_PROTO_TLS
@ COAP_PROTO_TLS
Definition: coap_pdu.h:309
COAP_PROTO_WSS
@ COAP_PROTO_WSS
Definition: coap_pdu.h:311
COAP_PROTO_TCP
@ COAP_PROTO_TCP
Definition: coap_pdu.h:308

Definition at line 37 of file coap_session.h.

## Typedef Documentation

## ◆ coap_fixed_point_t

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.

1,000 fractional bits equals one integer

## ◆ coap_session_state_t

typedef enum coap_session_state_t coap_session_state_t

coap_session_state_t values

## ◆ coap_session_type_t

typedef enum coap_session_type_t coap_session_type_t

coap_session_type_t values

## Enumeration Type Documentation

## ◆ coap_session_state_t

enum 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

enum 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

  endpoint | The CoAP endpoint.
  mtu | maximum message size

## ◆ coap_free_endpoint()

void coap_free_endpoint | ( | coap_endpoint_t * | endpoint | ) |

Release an endpoint and all the structures associated with it.

Parameters

  endpoint | The endpoint to release.

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

  ctx | The CoAP context.
  local_if | Address 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.
  server | The server's address. If the port number is zero, the default port for the protocol will be used.
  proto | Protocol.

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

  ctx | The CoAP context.
  local_if | Address 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.
  server | The server's address. If the port number is zero, the default port for the protocol will be used.
  proto | CoAP Protocol.
  setup_data | PKI 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

  ctx | The CoAP context.
  local_if | Address 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.
  server | The server's address. If the port number is zero, the default port for the protocol will be used.
  proto | Protocol.
  identity | PSK client identity
  key | PSK shared key
  key_len | PSK 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

  ctx | The CoAP context.
  local_if | Address 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.
  server | The server's address. If the port number is zero, the default port for the protocol will be used.
  proto | CoAP Protocol.
  setup_data | PSK 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

  context | The coap context that will own the new endpoint,
  listen_addr | Address 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.
  proto | Protocol used on this endpoint,

Returns
  The new endpoint or `NULL` on failure.

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

  session | The CoAP session.
  reason | The reason why the session was disconnected.

Definition at line 848 of file coap_session.c.

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

  session | The 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

  session | The 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

  session | The 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

  session | The 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

  context | The context to search.
  remote_addr | The remote (peer) address to search for.
  ifindex | The Interface index that is used to access remote_addr.

Returns
  The found session or `NULL` if not found.

Definition at line 1848 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

  session | The 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

  session | The 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

  session | The 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

  session | The 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

  session | The 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

  session | The 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

  session | The 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

  session | The CoAP session.
  tls_lib | Updated with the library type.

Returns
  The session TLS ptr or `NULL` if not set up

Definition at line 1675 of file coap_session.c.

## ◆ coap_session_get_type()

coap_session_type_t coap_session_get_type | ( | const coap_session_t * | session | ) |

Get the session type.

Parameters

  session | The 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

  session | The current coap_session_t object.
  length | The length of the token (0 - 8 bytes).
  token | The token data.

Definition at line 1577 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

  session | The CoAP session.

Returns
  maximum PDU size, not including header (but including token).

Definition at line 608 of file coap_session.c.

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

  session | The current coap_session_t object.
  length | Updated with the length of the new token.
  token | Updated with the new token data (must be 8 bytes long).

Definition at line 1583 of file coap_session.c.

## ◆ coap_session_reference()

coap_session_t * coap_session_reference | ( | coap_session_t * | session | ) |

Increment reference counter on a session.

Parameters

  session | The CoAP session.

Returns
  same as session

Definition at line 348 of file coap_session.c.

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

  session | The CoAP session.

Definition at line 354 of file coap_session.c.

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

  session | The CoAP session.
  data | The 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

  session | The CoAP session.
  mtu | maximum message size

Definition at line 635 of file coap_session.c.

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

  session | The CoAP session.

Returns
  `1` if updated, `0` on failure.