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