libcoap 4.3.2rc2

coap_session.h
Go to the documentation of this file.
1/* coap_session.h -- Session management for libcoap
2*
3* Copyright (C) 2017 Jean-Claue Michelou <jcm@spinetix.com>
4*
5 * SPDX-License-Identifier: BSD-2-Clause
6 *
7* This file is part of the CoAP library libcoap. Please see
8* README for terms of use.
9*/
10
16#ifndef COAP_SESSION_H_
17#define COAP_SESSION_H_
18
30 typedef struct coap_fixed_point_t {
31 uint16_t integer_part;
32 uint16_t fractional_part;
34} coap_fixed_point_t;
35
36#define COAP_PROTO_NOT_RELIABLE(p) ((p)==COAP_PROTO_UDP || (p)==COAP_PROTO_DTLS)
37#define COAP_PROTO_RELIABLE(p) ((p)==COAP_PROTO_TCP || (p)==COAP_PROTO_TLS || \
38 (p)==COAP_PROTO_WS || (p)==COAP_PROTO_WSS)
39
43 typedef enum coap_session_type_t {
44 COAP_SESSION_TYPE_NONE = 0,
45 COAP_SESSION_TYPE_CLIENT,
46 COAP_SESSION_TYPE_SERVER,
47 COAP_SESSION_TYPE_HELLO,
49} coap_session_type_t;
50
54 typedef enum coap_session_state_t {
55 COAP_SESSION_STATE_NONE = 0,
56 COAP_SESSION_STATE_CONNECTING,
57 COAP_SESSION_STATE_HANDSHAKE,
58 COAP_SESSION_STATE_CSM,
59 COAP_SESSION_STATE_ESTABLISHED,
60} coap_session_state_t;
61
68 coap_session_t *coap_session_reference(coap_session_t *session);
69
77 void coap_session_release(coap_session_t *session);
78
86 void coap_session_disconnected(coap_session_t *session,
87 coap_nack_reason_t reason);
88
96 void coap_session_set_app_data(coap_session_t *session, void *data);
97
107 void *coap_session_get_app_data(const coap_session_t *session);
108
120 const coap_address_t *coap_session_get_addr_remote(
121 const coap_session_t *session);
122
134 const coap_address_t *coap_session_get_addr_mcast(
135 const coap_session_t *session);
136
144 const coap_address_t *coap_session_get_addr_local(
145 const coap_session_t *session);
146
154 coap_proto_t coap_session_get_proto(const coap_session_t *session);
155
163 coap_session_type_t coap_session_get_type(const coap_session_t *session);
164
172 coap_session_state_t coap_session_get_state(const coap_session_t *session);
173
181 int coap_session_get_ifindex(const coap_session_t *session);
182
196 void *coap_session_get_tls(const coap_session_t *session,
197 coap_tls_library_t *tls_lib);
198
206 coap_context_t *coap_session_get_context(const coap_session_t *session);
207
219 int coap_session_set_type_client(coap_session_t *session);
220
228 void coap_session_set_mtu(coap_session_t *session, unsigned mtu);
229
236 size_t coap_session_max_pdu_size(const coap_session_t *session);
237
247 coap_session_t *coap_new_client_session(
248 coap_context_t *ctx,
249 const coap_address_t *local_if,
250 const coap_address_t *server,
251 coap_proto_t proto
252);
253
269 coap_session_t *coap_new_client_session_psk(
270 coap_context_t *ctx,
271 const coap_address_t *local_if,
272 const coap_address_t *server,
273 coap_proto_t proto,
274 const char *identity,
275 const uint8_t *key,
276 unsigned key_len
277);
278
294 coap_session_t *coap_new_client_session_psk2(
295 coap_context_t *ctx,
296 const coap_address_t *local_if,
297 const coap_address_t *server,
298 coap_proto_t proto,
299 coap_dtls_cpsk_t *setup_data
300);
301
309 const coap_bin_const_t *coap_session_get_psk_hint(
310 const coap_session_t *session);
311
319 const coap_bin_const_t *coap_session_get_psk_identity(
320 const coap_session_t *session);
328 const coap_bin_const_t *coap_session_get_psk_key(
329 const coap_session_t *session);
330
346 coap_session_t *coap_new_client_session_pki(
347 coap_context_t *ctx,
348 const coap_address_t *local_if,
349 const coap_address_t *server,
350 coap_proto_t proto,
351 coap_dtls_pki_t *setup_data
352);
353
362 void coap_session_init_token(coap_session_t *session, size_t length,
363 const uint8_t *token);
364
373 void coap_session_new_token(coap_session_t *session, size_t *length,
374 uint8_t *token);
375
383 const char *coap_session_str(const coap_session_t *session);
384
397 coap_endpoint_t *coap_new_endpoint(coap_context_t *context, const coap_address_t *listen_addr,
398 coap_proto_t proto);
399
407 void coap_endpoint_set_default_mtu(coap_endpoint_t *endpoint, unsigned mtu);
408
414 void coap_free_endpoint(coap_endpoint_t *endpoint);
415
425 coap_session_t *coap_session_get_by_peer(const coap_context_t *context,
426 const coap_address_t *remote_addr,
427 int ifindex);
428
438 const char *coap_endpoint_str(const coap_endpoint_t *endpoint);
439
458#define COAP_DEFAULT_ACK_TIMEOUT ((coap_fixed_point_t){2,0})
459
467#define COAP_DEFAULT_ACK_RANDOM_FACTOR ((coap_fixed_point_t){1,500})
468
475#define COAP_DEFAULT_MAX_RETRANSMIT (4U)
476
484#define COAP_DEFAULT_NSTART (1U)
485
492#define COAP_DEFAULT_DEFAULT_LEISURE ((coap_fixed_point_t){5,0})
493
500#define COAP_DEFAULT_PROBING_RATE (1U)
501
509#define COAP_DEFAULT_MAX_PAYLOADS (10U)
510
518#define COAP_DEFAULT_NON_MAX_RETRANSMIT (4U)
519
527#define COAP_DEFAULT_NON_TIMEOUT ((coap_fixed_point_t){2,0})
528
536#define COAP_DEFAULT_NON_RECEIVE_TIMEOUT ((coap_fixed_point_t){4,0})
537
542#define COAP_DEFAULT_MAX_LATENCY (100U)
543
555 void coap_session_set_ack_timeout(coap_session_t *session,
556 coap_fixed_point_t value);
557
569 coap_fixed_point_t coap_session_get_ack_timeout(const coap_session_t *session);
570
582 void coap_session_set_ack_random_factor(coap_session_t *session,
583 coap_fixed_point_t value);
584
596 coap_fixed_point_t coap_session_get_ack_random_factor(
597 const coap_session_t *session);
598
609 void coap_session_set_max_retransmit(coap_session_t *session,
610 uint16_t value);
611
622uint16_t coap_session_get_max_retransmit(const coap_session_t *session);
623
632 void coap_session_set_nstart(coap_session_t *session,
633 uint16_t value);
634
643uint16_t coap_session_get_nstart(const coap_session_t *session);
644
653 void coap_session_set_default_leisure(coap_session_t *session,
654 coap_fixed_point_t value);
655
664 coap_fixed_point_t coap_session_get_default_leisure(
665 const coap_session_t *session);
666
675 void coap_session_set_probing_rate(coap_session_t *session, uint32_t value);
676
685uint32_t coap_session_get_probing_rate(const coap_session_t *session);
686
696 void coap_session_set_max_payloads(coap_session_t *session,
697 uint16_t value);
698
708uint16_t coap_session_get_max_payloads(const coap_session_t *session);
709
719 void coap_session_set_non_max_retransmit(coap_session_t *session,
720 uint16_t value);
721
731uint16_t coap_session_get_non_max_retransmit(const coap_session_t *session);
732
744 void coap_session_set_non_timeout(coap_session_t *session,
745 coap_fixed_point_t value);
746
758 coap_fixed_point_t coap_session_get_non_timeout(const coap_session_t *session);
759
770 void coap_session_set_non_receive_timeout(coap_session_t *session,
771 coap_fixed_point_t value);
772
783 coap_fixed_point_t coap_session_get_non_receive_timeout(
784 const coap_session_t *session);
785
793 coap_mid_t coap_session_send_ping(coap_session_t *session);
794
800 void coap_session_set_no_observe_cancel(coap_session_t *session);
801
802#endif /* COAP_SESSION_H */
coap_nack_reason_t
coap_nack_reason_t
Definition: coap_io.h:69
coap_session_send_ping
coap_mid_t coap_session_send_ping(coap_session_t *session)
Send a ping message for the session.
Definition: coap_session.c:738
coap_session_set_no_observe_cancel
void coap_session_set_no_observe_cancel(coap_session_t *session)
Disable client automatically sending observe cancel on session close.
coap_session_get_non_max_retransmit
uint16_t coap_session_get_non_max_retransmit(const coap_session_t *session)
Get the CoAP NON maximum retransmit count of missing Q-Block1 or Q-Block2 requested before there is a...
Definition: coap_session.c:318
coap_session_get_default_leisure
coap_fixed_point_t coap_session_get_default_leisure(const coap_session_t *session)
Get the CoAP default leisure time RFC7252 DEFAULT_LEISURE.
Definition: coap_session.c:298
coap_session_set_max_retransmit
void coap_session_set_max_retransmit(coap_session_t *session, uint16_t value)
Set the CoAP maximum retransmit count before failure.
Definition: coap_session.c:174
coap_session_get_non_timeout
coap_fixed_point_t coap_session_get_non_timeout(const coap_session_t *session)
Get the CoAP MAX_PAYLOADS limit delay timeout.
Definition: coap_session.c:328
coap_session_set_ack_random_factor
void coap_session_set_ack_random_factor(coap_session_t *session, coap_fixed_point_t value)
Set the CoAP ack randomize factor.
Definition: coap_session.c:158
coap_session_get_ack_random_factor
coap_fixed_point_t coap_session_get_ack_random_factor(const coap_session_t *session)
Get the CoAP ack randomize factor.
Definition: coap_session.c:283
coap_session_get_max_retransmit
uint16_t coap_session_get_max_retransmit(const coap_session_t *session)
Get the CoAP maximum retransmit before failure.
Definition: coap_session.c:288
coap_session_set_max_payloads
void coap_session_set_max_payloads(coap_session_t *session, uint16_t value)
Set the CoAP maximum payloads count of Q-Block1 or Q-Block2 before delay is introduced RFC9177 MAX_PA...
Definition: coap_session.c:212
coap_session_get_probing_rate
uint32_t coap_session_get_probing_rate(const coap_session_t *session)
Get the CoAP probing rate when there is no response RFC7252 PROBING_RATE.
Definition: coap_session.c:303
coap_session_set_ack_timeout
void coap_session_set_ack_timeout(coap_session_t *session, coap_fixed_point_t value)
Set the CoAP initial ack response timeout before the next re-transmit.
Definition: coap_session.c:148
coap_session_set_non_receive_timeout
void coap_session_set_non_receive_timeout(coap_session_t *session, coap_fixed_point_t value)
Set the CoAP non receive timeout delay timeout.
Definition: coap_session.c:262
coap_session_set_nstart
void coap_session_set_nstart(coap_session_t *session, uint16_t value)
Set the CoAP maximum concurrent transmission count of Confirmable messages RFC7252 NSTART.
Definition: coap_session.c:183
coap_session_set_non_max_retransmit
void coap_session_set_non_max_retransmit(coap_session_t *session, uint16_t value)
Set the CoAP NON maximum retransmit count of missing Q-Block1 or Q-Block2 requested before there is a...
Definition: coap_session.c:228
coap_session_get_max_payloads
uint16_t coap_session_get_max_payloads(const coap_session_t *session)
Get the CoAP maximum payloads count of Q-Block1 or Q-Block2 before delay is introduced RFC9177 MAX_PA...
Definition: coap_session.c:308
coap_session_set_probing_rate
void coap_session_set_probing_rate(coap_session_t *session, uint32_t value)
Set the CoAP probing rate when there is no response RFC7252 PROBING_RATE.
Definition: coap_session.c:203
coap_session_set_default_leisure
void coap_session_set_default_leisure(coap_session_t *session, coap_fixed_point_t value)
Set the CoAP default leisure time (for multicast) RFC7252 DEFAULT_LEISURE.
Definition: coap_session.c:192
coap_session_get_non_receive_timeout
coap_fixed_point_t coap_session_get_non_receive_timeout(const coap_session_t *session)
Get the CoAP non receive timeout delay timeout.
Definition: coap_session.c:338
coap_session_get_nstart
uint16_t coap_session_get_nstart(const coap_session_t *session)
Get the CoAP maximum concurrent transmission count of Confirmable messages RFC7252 NSTART.
Definition: coap_session.c:293
coap_session_get_ack_timeout
coap_fixed_point_t coap_session_get_ack_timeout(const coap_session_t *session)
Get the CoAP initial ack response timeout before the next re-transmit.
Definition: coap_session.c:278
coap_session_set_non_timeout
void coap_session_set_non_timeout(coap_session_t *session, coap_fixed_point_t value)
Set the CoAP non timeout delay timeout.
Definition: coap_session.c:244
coap_tls_library_t
coap_tls_library_t
Definition: coap_dtls.h:92
coap_endpoint_str
const char * coap_endpoint_str(const coap_endpoint_t *endpoint)
Get endpoint description.
coap_session_str
const char * coap_session_str(const coap_session_t *session)
Get session description.
Definition: coap_session.c:1881
coap_mid_t
int coap_mid_t
coap_mid_t is used to store the CoAP Message ID of a CoAP PDU.
Definition: coap_pdu.h:255
coap_proto_t
coap_proto_t
CoAP protocol types.
Definition: coap_pdu.h:304
coap_session_type_t
coap_session_type_t
coap_session_type_t values
Definition: coap_session.h:43
coap_session_set_mtu
void coap_session_set_mtu(coap_session_t *session, unsigned mtu)
Set the session MTU.
Definition: coap_session.c:635
coap_session_get_context
coap_context_t * coap_session_get_context(const coap_session_t *session)
Get the session context.
Definition: coap_session.c:1624
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.
Definition: coap_session.c:1605
coap_session_get_proto
coap_proto_t coap_session_get_proto(const coap_session_t *session)
Get the session protocol type.
Definition: coap_session.c:1631
coap_session_max_pdu_size
size_t coap_session_max_pdu_size(const coap_session_t *session)
Get maximum acceptable PDU size.
Definition: coap_session.c:608
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).
Definition: coap_session.c:1483
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)
Definition: coap_session.c:1675
coap_session_get_state
coap_session_state_t coap_session_get_state(const coap_session_t *session)
Get the session state.
Definition: coap_session.c:1661
coap_free_endpoint
void coap_free_endpoint(coap_endpoint_t *endpoint)
Release an endpoint and all the structures associated with it.
coap_session_state_t
coap_session_state_t
coap_session_state_t values
Definition: coap_session.h:54
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.
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.
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.
Definition: coap_session.c:1577
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.
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.
Definition: coap_session.c:1583
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).
Definition: coap_session.c:1471
coap_session_set_app_data
void coap_session_set_app_data(coap_session_t *session, void *data)
Stores data with the given session.
Definition: coap_session.c:376
coap_session_release
void coap_session_release(coap_session_t *session)
Decrement reference counter on a session.
Definition: coap_session.c:354
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.
Definition: coap_session.c:1848
coap_endpoint_set_default_mtu
void coap_endpoint_set_default_mtu(coap_endpoint_t *endpoint, unsigned mtu)
Set the endpoint's default MTU.
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).
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.
Definition: coap_session.c:1598
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.
coap_session_set_type_client
int coap_session_set_type_client(coap_session_t *session)
Set the session type to client.
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.
coap_session_disconnected
void coap_session_disconnected(coap_session_t *session, coap_nack_reason_t reason)
Notify session that it has failed.
Definition: coap_session.c:848
coap_fixed_point_t
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.
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...
Definition: coap_session.c:1612
coap_session_reference
coap_session_t * coap_session_reference(coap_session_t *session)
Increment reference counter on a session.
Definition: coap_session.c:348
coap_session_get_ifindex
int coap_session_get_ifindex(const coap_session_t *session)
Get the session if index.
Definition: coap_session.c:1668
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_sessi...
Definition: coap_session.c:382
coap_session_get_type
coap_session_type_t coap_session_get_type(const coap_session_t *session)
Get the session type.
Definition: coap_session.c:1638
COAP_SESSION_TYPE_NONE
@ COAP_SESSION_TYPE_NONE
Not defined.
Definition: coap_session.h:44
COAP_SESSION_TYPE_HELLO
@ COAP_SESSION_TYPE_HELLO
server-side ephemeral session for responding to a client hello
Definition: coap_session.h:47
COAP_SESSION_TYPE_SERVER
@ COAP_SESSION_TYPE_SERVER
server-side
Definition: coap_session.h:46
COAP_SESSION_TYPE_CLIENT
@ COAP_SESSION_TYPE_CLIENT
client-side
Definition: coap_session.h:45
COAP_SESSION_STATE_HANDSHAKE
@ COAP_SESSION_STATE_HANDSHAKE
Definition: coap_session.h:57
COAP_SESSION_STATE_CSM
@ COAP_SESSION_STATE_CSM
Definition: coap_session.h:58
COAP_SESSION_STATE_ESTABLISHED
@ COAP_SESSION_STATE_ESTABLISHED
Definition: coap_session.h:59
COAP_SESSION_STATE_NONE
@ COAP_SESSION_STATE_NONE
Definition: coap_session.h:55
COAP_SESSION_STATE_CONNECTING
@ COAP_SESSION_STATE_CONNECTING
Definition: coap_session.h:56
coap_address_t
Multi-purpose address abstraction.
Definition: coap_address.h:109
coap_bin_const_t
CoAP binary data definition with const data.
Definition: coap_str.h:64
coap_context_t
The CoAP stack's global state is stored in a coap_context_t object.
Definition: coap_net_internal.h:49
coap_dtls_cpsk_t
The structure used for defining the Client PSK setup data to be used.
Definition: coap_dtls.h:378
coap_dtls_pki_t
The structure used for defining the PKI setup data to be used.
Definition: coap_dtls.h:284
coap_endpoint_t
Abstraction of virtual endpoint that can be attached to coap_context_t.
Definition: coap_session_internal.h:219
coap_fixed_point_t
Abstraction of a fixed point number that can be used where necessary instead of a float.
Definition: coap_session.h:30
coap_fixed_point_t::fractional_part
uint16_t fractional_part
Fractional part of fixed point variable 1/1000 (3 points) precision.
Definition: coap_session.h:32
coap_fixed_point_t::integer_part
uint16_t integer_part
Integer part of fixed point variable.
Definition: coap_session.h:31
coap_session_t
Abstraction of virtual session that can be attached to coap_context_t (client) or coap_endpoint_t (se...
Definition: coap_session_internal.h:68