coap_session.h

Go to the documentation of this file.

/* coap_session.h -- Session management for libcoap
 *
 * Copyright (C) 2017 Jean-Claue Michelou <jcm@spinetix.com>
 * Copyright (C) 2023-2025 Jon Shallow <supjps-libcoap@jpshallow.com>
 *
 * SPDX-License-Identifier: BSD-2-Clause
 *
 * This file is part of the CoAP library libcoap. Please see
 * README for terms of use.
*/
 
#ifndef COAP_SESSION_H_
#define COAP_SESSION_H_
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef struct coap_fixed_point_t {
  uint16_t integer_part;    
  uint16_t fractional_part; 
} coap_fixed_point_t;
 
#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 || \
                                (p)==COAP_PROTO_WS || (p)==COAP_PROTO_WSS)
 
typedef 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;
 
typedef 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;
 
COAP_API coap_session_t *coap_session_reference(coap_session_t *session);
 
COAP_API void coap_session_release(coap_session_t *session);
 
COAP_API void coap_session_disconnected(coap_session_t *session,
                                        coap_nack_reason_t reason);
 
COAP_DEPRECATED void coap_session_set_app_data(coap_session_t *session,
                                               void *data);
 
void *coap_session_get_app_data(const coap_session_t *session);
 
typedef void (*coap_app_data_free_callback_t)(void *data);
 
COAP_API void *coap_session_set_app_data2(coap_session_t *session, void *data,
                                          coap_app_data_free_callback_t callback);
 
const coap_address_t *coap_session_get_addr_remote(
    const coap_session_t *session);
 
const coap_address_t *coap_session_get_addr_mcast(
    const coap_session_t *session);
 
const coap_address_t *coap_session_get_addr_local(
    const coap_session_t *session);
 
coap_proto_t coap_session_get_proto(const coap_session_t *session);
 
coap_session_type_t coap_session_get_type(const coap_session_t *session);
 
coap_session_state_t coap_session_get_state(const coap_session_t *session);
 
coap_endpoint_t *coap_session_get_endpoint(const coap_session_t *session);
 
int coap_session_get_ifindex(const coap_session_t *session);
 
void *coap_session_get_tls(const coap_session_t *session,
                           coap_tls_library_t *tls_lib);
 
coap_context_t *coap_session_get_context(const coap_session_t *session);
 
COAP_API int coap_session_set_type_client(coap_session_t *session);
 
COAP_API int coap_session_set_type_server(coap_session_t *session);
 
void coap_session_set_mtu(coap_session_t *session, unsigned mtu);
 
COAP_API size_t coap_session_max_pdu_size(const coap_session_t *session);
 
COAP_API 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
                                                );
 
COAP_API 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
                                                    );
 
COAP_API 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
                                                     );
 
const coap_bin_const_t *coap_session_get_psk_hint(
    const coap_session_t *session);
 
const coap_bin_const_t *coap_session_get_psk_identity(
    const coap_session_t *session);
const coap_bin_const_t *coap_session_get_psk_key(
    const coap_session_t *session);
 
COAP_API 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
                                                    );
 
void coap_session_init_token(coap_session_t *session, size_t length,
                             const uint8_t *token);
 
void coap_session_new_token(coap_session_t *session, size_t *length,
                            uint8_t *token);
 
const char *coap_session_str(const coap_session_t *session);
 
COAP_API coap_endpoint_t *coap_new_endpoint(coap_context_t *context,
                                            const coap_address_t *listen_addr,
                                            coap_proto_t proto);
 
void coap_endpoint_set_default_mtu(coap_endpoint_t *endpoint, unsigned mtu);
 
COAP_API void coap_free_endpoint(coap_endpoint_t *endpoint);
 
void *coap_endpoint_get_app_data(const coap_endpoint_t *endpoint);
 
COAP_API void *coap_endpoint_set_app_data(coap_endpoint_t *endpoint, void *data,
                                          coap_app_data_free_callback_t callback);
 
coap_session_t *coap_session_get_by_peer(const coap_context_t *context,
                                         const coap_address_t *remote_addr,
                                         int ifindex);
 
const char *coap_endpoint_str(const coap_endpoint_t *endpoint);
 
#define COAP_DEFAULT_ACK_TIMEOUT ((coap_fixed_point_t){2,0})
 
#define COAP_DEFAULT_ACK_RANDOM_FACTOR ((coap_fixed_point_t){1,500})
 
#define COAP_DEFAULT_MAX_RETRANSMIT  (4U)
 
#define COAP_DEFAULT_NSTART (1U)
 
#define COAP_DEFAULT_DEFAULT_LEISURE ((coap_fixed_point_t){5,0})
 
#define COAP_DEFAULT_PROBING_RATE (1U)
 
#define COAP_DEFAULT_MAX_PAYLOADS (10U)
 
#define COAP_DEFAULT_NON_MAX_RETRANSMIT (4U)
 
#define COAP_DEFAULT_NON_TIMEOUT ((coap_fixed_point_t){2,0})
 
#define COAP_DEFAULT_NON_RECEIVE_TIMEOUT ((coap_fixed_point_t){4,0})
 
#define COAP_DEFAULT_MAX_LATENCY (100U)
 
void coap_session_set_ack_timeout(coap_session_t *session,
                                  coap_fixed_point_t value);
 
coap_fixed_point_t coap_session_get_ack_timeout(const coap_session_t *session);
 
void coap_session_set_ack_random_factor(coap_session_t *session,
                                        coap_fixed_point_t value);
 
coap_fixed_point_t coap_session_get_ack_random_factor(
    const coap_session_t *session);
 
void coap_session_set_max_retransmit(coap_session_t *session,
                                     uint16_t value);
 
uint16_t coap_session_get_max_retransmit(const coap_session_t *session);
 
void coap_session_set_nstart(coap_session_t *session,
                             uint16_t value);
 
uint16_t coap_session_get_nstart(const coap_session_t *session);
 
void coap_session_set_default_leisure(coap_session_t *session,
                                      coap_fixed_point_t value);
 
coap_fixed_point_t coap_session_get_default_leisure(
    const coap_session_t *session);
 
void coap_session_set_probing_rate(coap_session_t *session, uint32_t value);
 
uint32_t coap_session_get_probing_rate(const coap_session_t *session);
 
void coap_session_set_max_payloads(coap_session_t *session,
                                   uint16_t value);
 
uint16_t coap_session_get_max_payloads(const coap_session_t *session);
 
void coap_session_set_non_max_retransmit(coap_session_t *session,
                                         uint16_t value);
 
uint16_t coap_session_get_non_max_retransmit(const coap_session_t *session);
 
void coap_session_set_non_timeout(coap_session_t *session,
                                  coap_fixed_point_t value);
 
coap_fixed_point_t coap_session_get_non_timeout(const coap_session_t *session);
 
void coap_session_set_non_receive_timeout(coap_session_t *session,
                                          coap_fixed_point_t value);
 
coap_fixed_point_t coap_session_get_non_receive_timeout(
    const coap_session_t *session);
 
COAP_API coap_mid_t coap_session_send_ping(coap_session_t *session);
 
void coap_session_set_no_observe_cancel(coap_session_t *session);
 
#ifdef __cplusplus
}
#endif
 
#endif  /* COAP_SESSION_H */