/* session.h -- Session management for libcoap * * Copyright (C) 2017 Jean-Claue Michelou * * This file is part of the CoAP library libcoap. Please see * README for terms of use. */ #ifndef _SESSION_H_ #define _SESSION_H_ #include "coap_io.h" #include "pdu.h" struct coap_endpoint_t; struct coap_contex_t; typedef uint8_t coap_proto_t; /** * coap_proto_t values */ #define COAP_PROTO_NONE 0 #define COAP_PROTO_UDP 1 #define COAP_PROTO_DTLS 2 typedef uint8_t coap_session_type_t; /** * coap_session_type_t values */ #define COAP_SESSION_TYPE_CLIENT 1 /**< client-side */ #define COAP_SESSION_TYPE_SERVER 2 /**< server-side */ #define COAP_SESSION_TYPE_HELLO 3 /**< server-side ephemeral session for responding to a client hello */ typedef uint8_t coap_session_state_t; /** * coap_session_state_t values */ #define COAP_SESSION_STATE_NONE 0 #define COAP_SESSION_STATE_CONNECTING 1 #define COAP_SESSION_STATE_HANDSHAKE 2 #define COAP_SESSION_STATE_ESTABLISHED 3 typedef struct coap_pdu_queue_t { struct coap_pdu_queue_t *next; coap_pdu_t *pdu; int retransmit_cnt; } coap_pdu_queue_t; typedef struct coap_session_t { struct coap_session_t *next; coap_proto_t proto; /**< protocol used */ coap_session_type_t type; /**< client or server side socket */ coap_session_state_t state; /**< current state of relationaship with peer */ int ref; /**< reference count from queues */ coap_address_t local_addr; /**< local address and port */ coap_address_t remote_addr; /**< remote address and port */ int ifindex; /**< interface index */ coap_socket_t sock; /**< socket object for the session, if any */ struct coap_endpoint_t *endpoint; /**< session's endpoint */ struct coap_context_t *context; /**< session's context */ void *tls; /**< security parameters */ coap_pdu_queue_t *sendqueue; /**< list of messages waiting to be sent */ char *psk_identity; uint8_t *psk_key; unsigned psk_key_len; } coap_session_t; /** * Increment reference counter on a session. * * @param session The CoAP session. * @return same as session */ coap_session_t *coap_session_reference( 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. * * @param session The CoAP session. */ void coap_session_release( coap_session_t *session ); /** * Notify session that it has failed connecting or has been disconnected. * * @param session The CoAP session. */ void coap_session_disconnected( coap_session_t *session ); /** * Notify session that it has just connected or reconnected. * * @param session The CoAP session. */ void coap_session_connected( coap_session_t *session ); /** * Creates a new client session to the designated server. * @param ctx The CoAP context. * @param 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. * @param server The server's address. If the port number is zero, the default port for the protocol will be used. * @param proto Protocol. * * @return A new CoAP session or NULL if failed. Call coap_session_release to free. */ coap_session_t *coap_new_client_session( struct 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 with PSK credentials * @param ctx The CoAP context. * @param 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. * @param server The server's address. If the port number is zero, the default port for the protocol will be used. * @param identity PSK client identity * @param identity_len Length PSK client identity * @param key PSK shared key * @param key_len PSK shared key length * @param proto Protocol. * * @return A new CoAP session or NULL if failed. Call coap_session_release to free. */ coap_session_t *coap_new_client_session_psk( struct 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 ); /** * Function interface for data transmission. This function returns the number of * bytes that have been transmitted, or a value less than zero on error. * * @param session Session to send data on. * @param data The data to send. * @param datalen The actual length of @p data. * * @return The number of bytes written on success, or a value * less than zero on error. */ ssize_t coap_session_send( coap_session_t *session, const uint8_t *data, size_t datalen ); /** * Get session description. * * @param session The CoAP session. * @return description string */ const char *coap_session_str( const coap_session_t *session ); ssize_t coap_session_delay_pdu( coap_session_t *session, coap_pdu_t *pdu, int retransmit_cnt ); /** * Abstraction of virtual endpoint that can be attached to coap_context_t. The * tuple (handle, addr) must uniquely identify this endpoint. */ typedef struct coap_endpoint_t { struct coap_endpoint_t *next; struct coap_context_t *context; /**< endpoint's context */ coap_proto_t proto; /**< protocol used on this interface */ coap_socket_t sock; /**< socket object for the interface, if any */ coap_address_t bind_addr; /**< local interface address */ coap_session_t *sessions; /**< list of active sessions */ coap_session_t hello; /**< special session of DTLS hello messages */ } coap_endpoint_t; /** * Create a new endpoint for communicating with peers. * * @param context The coap context that will own the new endpoint * @param 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. * @param proto Protocol used on this endpoint */ coap_endpoint_t *coap_new_endpoint( struct coap_context_t *context, const coap_address_t *listen_addr, coap_proto_t proto ); void coap_free_endpoint( coap_endpoint_t *ep ); /** * Get endpoint description. * * @param session The CoAP endpoint. * @return description string */ const char *coap_endpoint_str( const coap_endpoint_t *endpoint ); /** * Lookup the server session for the packet received on an endpoint, or create * a new one. * * @param endpoint Active endpoint the packet was received on. * @param packet Received packet. * @return The CoAP session. */ coap_session_t *coap_endpoint_get_session( coap_endpoint_t *endpoint, const struct coap_packet_t *packet ); coap_session_t *coap_endpoint_new_dtls_session( coap_endpoint_t *endpoint, const struct coap_packet_t *packet ); coap_session_t *coap_session_get_by_peer( struct coap_context_t *ctx, const struct coap_address_t *remote_addr, int ifindex ); #endif /* _SESSION_H */