1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc,tw=0: 3 4coap_session(3) 5=============== 6:doctype: manpage 7:man source: coap_session 8:man version: @PACKAGE_VERSION@ 9:man manual: libcoap Manual 10 11NAME 12---- 13coap_session, 14coap_session_reference, 15coap_session_release, 16coap_session_disconnected, 17coap_session_set_type_client, 18coap_session_set_app_data, 19coap_session_get_app_data, 20coap_session_get_addr_local, 21coap_session_get_addr_remote, 22coap_session_get_context, 23coap_session_get_ifindex, 24coap_session_get_proto, 25coap_session_get_state, 26coap_session_get_tls, 27coap_session_get_type, 28coap_session_get_psk_hint, 29coap_session_get_psk_key 30- Work with CoAP sessions 31 32SYNOPSIS 33-------- 34*#include <coap@LIBCOAP_API_VERSION@/coap.h>* 35 36*coap_session_t *coap_session_reference(coap_session_t *_session_);* 37 38*void coap_session_release(coap_session_t *_session_);* 39 40*void coap_session_disconnected(coap_session_t *_session_, coap_nack_reason_t _reason_);* 41 42*int coap_session_set_type_client(coap_session_t *_session_);* 43 44*void coap_session_set_app_data(coap_session_t *_session_, void *_data_);* 45 46*void *coap_session_get_app_data(const coap_session_t *_session_);* 47 48*const coap_address_t *coap_session_get_addr_local( 49const coap_session_t *_session_);* 50 51*const coap_address_t *coap_session_get_addr_remote( 52const coap_session_t *_session_);* 53 54*coap_context_t *coap_session_get_context(const coap_session_t *_session_);* 55 56*int coap_session_get_ifindex(const coap_session_t *_session_);* 57 58*coap_proto_t coap_session_get_proto(const coap_session_t *_session_);* 59 60*coap_session_state_t coap_session_get_state(const coap_session_t *_session_);* 61 62*void *coap_session_get_tls(const coap_session_t *_session_, 63coap_tls_library_t *tls_lib);* 64 65*coap_session_type_t coap_session_get_type(const coap_session_t *_session_);* 66 67*const coap_bin_const_t *coap_session_get_psk_hint( 68const coap_session_t *_session_);* 69 70*const coap_bin_const_t *coap_session_get_psk_key( 71const coap_session_t *_session_);* 72 73For specific (D)TLS library support, link with 74*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*, 75*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls* 76or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*. Otherwise, link with 77*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support. 78 79DESCRIPTION 80----------- 81This man page focuses on the CoAP Session and how to update or get information 82from the opaque coap_session_t structure. 83 84A CoAP Session maintains the state of an ongoing connection between a Client 85and Server which is stored in a coap_session_t Session object. A CoAP session 86is tracked by local port, CoAP protocol, remote IP address and remote port. 87 88The Session network traffic can be encrypted or un-encrypted if there is an 89underlying TLS library. 90 91The *coap_session_reference*() function is used to increment the reference 92count of the _session_. Incrementing the reference count by an application 93means that the library will not inadvertently remove the session when it has 94finished processing the session. 95 96The *coap_session_release*() function is be used to decrement the _session_ 97reference count, which when it gets to 0, will:- 98 99If type Client, free off the session which then clears all entries from the 100receive queue and send queue. *NOTE:* All client sessions start off with a 101reference count of 1. 102 103If type Server, then the _session_ is added to an idle pool ready for subsequent 104re-use. If the Server _session_ is not used for 5 minutes, then it will get 105completely freed off. *NOTE:* Unless the application increments the 106reference count, this is the case for all type server sessions as they start 107with a reference count of 0. 108 109The *coap_session_disconnected*() function is used to force the closure of a 110_session_ for the reason _reason_. It will cause any outstanding traffic to 111get dropped. 112 113The *coap_session_set_type_client*() function is used to convert the _session_ 114frrm a session endpoint type of Server to Client. This typically is used in a 115Call-Home type environment where the roles have to change following the 116establishment of a session. The reference count is incremented by 1. 117 118The *coap_session_set_app_data*() function is used to define a _data_ pointer 119for the _session_ which can then be retrieved at a later date. 120 121The *coap_session_get_app_data*() function is used to retrieve the data 122pointer previously defined by *coap_session_set_app_data*(). 123 124The *coap_session_get_addr_local*() function is used to get the local IP 125address and port information from the _session_. 126 127The *coap_session_get_addr_remote*() function is used to get the remote (peer) 128IP address and port information from the _session_. 129 130The *coap_session_get_context*() function is used to get the CoAP context 131associated with the _session_. 132 133The *coap_session_get_ifindex*() function is used to get the network interface 134index that the traffic came in over from the _session_. 135 136[source, c] 137---- 138COAP_PROTO_UDP 139COAP_PROTO_DTLS 140COAP_PROTO_TCP 141COAP_PROTO_TLS 142---- 143 144The *coap_session_get_proto*() function is used to get the CoAP protocol from 145the _session_. 146 147[source, c] 148---- 149COAP_SESSION_STATE_NONE 150COAP_SESSION_STATE_CONNECTING 151COAP_SESSION_STATE_HANDSHAKE 152COAP_SESSION_STATE_CSM 153COAP_SESSION_STATE_ESTABLISHED 154---- 155 156The *coap_session_get_state*() function is used to get the current state 157of the _session_. 158 159[source, c] 160---- 161OpenSSL: SSL* 162GnuTLS: gnutls_session_t (implicit *) 163Mbed TLS: mbedtls_ssl_context* 164TinyDTLS: struct dtls_context* 165---- 166 167The *coap_session_get_tls*() function is used to get the pointer to the TLS 168information from the _session_. This is TLS library specific. _tls_lib_ is 169updated with the underlying (D)TLS library type. 170 171[source, c] 172---- 173COAP_SESSION_TYPE_CLIENT 174COAP_SESSION_TYPE_SERVER 175COAP_SESSION_TYPE_HELLO /* Negotiating a (D)TLS session */ 176---- 177 178The *coap_session_get_type*() function is used to get the session type from the 179_session_. 180 181The *coap_session_get_psk_hint*() function is used to get the current server 182_session_'s pre-shared-key identity hint. 183 184The *coap_session_get_psk_key*() function is used to get the current 185_session_'s pre-shared-key key information. 186 187RETURN VALUES 188------------- 189 190*coap_session_reference*() function returns a pointer to the session. 191 192*coap_session_set_type_client*() function returns 1 on success, otherwise 0. 193 194*coap_session_get_app_data*() function return a previously defined pointer. 195 196*coap_session_get_addr_local*() and *coap_session_get_addr_remote*() return 197a pointer to the IP address / port or NULL on error. 198 199*coap_session_get_context*() returns a pointer to the current CoAP Context or 200NULL on error. 201 202*coap_session_get_ifindex*() returns the network interface the traffic last 203came in over, or -1 on error. 204 205*coap_session_get_proto*() returns the current session's protocol or 0 on error. 206 207*coap_session_get_state*() returns the current session's state or 0 on error. 208 209*coap_session_get_tls*() returns a pointer to the current session's TLS 210information (TLS library dependent) or NULL if there is none or there is an 211error. 212 213*coap_session_get_type*() returns the current session's type or 0 on error. 214 215*coap_session_get_psk_hint*() returns the current server session's 216pre-shared-key identity hint, or NULL if not defined. 217 218*coap_session_get_psk_key*() returns the current session's pre-shared-key 219key information, or NULL if not defined. 220 221SEE ALSO 222-------- 223*coap_context*(3), *coap_endpoint_client*(3) and *coap_endpoint_server*(3) 224 225FURTHER INFORMATION 226------------------- 227See "RFC7252: The Constrained Application Protocol (CoAP)" for further 228information. 229 230BUGS 231---- 232Please report bugs on the mailing list for libcoap: 233libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at 234https://github.com/obgm/libcoap/issues 235 236AUTHORS 237------- 238The libcoap project <libcoap-developers@lists.sourceforge.net> 239