1COAP_SESSION(3) libcoap Manual COAP_SESSION(3)
2
6 coap_session, coap_session_reference, coap_session_release,
7 coap_session_disconnected, coap_session_set_type_client,
8 coap_session_set_app_data, coap_session_get_app_data,
9 coap_session_get_addr_local, coap_session_get_addr_remote - Work with
10 CoAP sessions
11
13 #include <coap3/coap.h>
14 coap_session_t *coap_session_reference(coap_session_t *session);
16 void coap_session_release(coap_session_t *session);
18 void coap_session_disconnected(coap_session_t *session,
20 coap_nack_reason_t reason);
21 int coap_session_set_type_client(coap_session_t *session);
23 void coap_session_set_app_data(coap_session_t *session, void *data);
25 void *coap_session_get_app_data(const coap_session_t *session);
27 const coap_address_t *coap_session_get_addr_local( const coap_session_t
29 *session);
30 const coap_address_t *coap_session_get_addr_remote( const
32 coap_session_t *session);
33 coap_context_t *coap_session_get_context(const coap_session_t
35 *session);
36 int coap_session_get_ifindex(const coap_session_t *session);
38 coap_proto_t coap_session_get_proto(const coap_session_t *session);
40 coap_session_state_t coap_session_get_state(const coap_session_t
42 *session);
43 void *coap_session_get_tls(const coap_session_t *session,
45 coap_tls_library_t *tls_lib);
46 coap_session_type_t coap_session_get_type(const coap_session_t
48 *session);
49 const coap_bin_const_t *coap_session_get_psk_hint( const coap_session_t
51 *session);
52 const coap_bin_const_t *coap_session_get_psk_key( const coap_session_t
54 *session);
55 For specific (D)TLS library support, link with -lcoap-3-notls,
57 -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or
58 -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default
59 (D)TLS library support.
60
62 This man page focuses on the CoAP Session and how to update or get
63 information from the opaque coap_session_t structure.
64 A CoAP Session maintains the state of an ongoing connection between a
66 Client and Server which is stored in a coap_session_t Session object. A
67 CoAP session is tracked by local port, CoAP protocol, remote IP address
68 and remote port.
69 The Session network traffic can be encrypted or un-encrypted if there
71 is an underlying TLS library.
72 The coap_session_reference() function is used to increment the
74 reference count of the session. Incrementing the reference count by an
75 application means that the library will not inadvertently remove the
76 session when it has finished processing the session.
77 The coap_session_release() function is be used to decrement the session
79 reference count, which when it gets to 0, will:-
80 If type Client, free off the session which then clears all entries from
82 the receive queue and send queue. NOTE: All client sessions start off
83 with a reference count of 1.
84 If type Server, then the session is added to an idle pool ready for
86 subsequent re-use. If the Server session is not used for 5 minutes,
87 then it will get completely freed off. NOTE: Unless the application
88 increments the reference count, this is the case for all type server
89 sessions as they start with a reference count of 0.
90 The coap_session_disconnected() function is used to force the closure
92 of a session for the reason reason. It will cause any outstanding
93 traffic to get dropped.
94 The coap_session_set_type_client() function is used to convert the
96 session frrm a session endpoint type of Server to Client. This
97 typically is used in a Call-Home type environment where the roles have
98 to change following the establishment of a session. The reference count
99 is incremented by 1.
100 The coap_session_set_app_data() function is used to define a data
102 pointer for the session which can then be retrieved at a later date.
103 The coap_session_get_app_data() function is used to retrieve the data
105 pointer previously defined by coap_session_set_app_data().
106 The coap_session_get_addr_local() function is used to get the local IP
108 address and port information from the session.
109 The coap_session_get_addr_remote() function is used to get the remote
111 (peer) IP address and port information from the session.
112 The coap_session_get_context() function is used to get the CoAP context
114 associated with the session.
115 The coap_session_get_ifindex() function is used to get the network
117 interface index that the traffic came in over from the session.
118 COAP_PROTO_UDP
120 COAP_PROTO_DTLS
121 COAP_PROTO_TCP
122 COAP_PROTO_TLS
123 The coap_session_get_proto() function is used to get the CoAP protocol
125 from the session.
126 COAP_SESSION_STATE_NONE
128 COAP_SESSION_STATE_CONNECTING
129 COAP_SESSION_STATE_HANDSHAKE
130 COAP_SESSION_STATE_CSM
131 COAP_SESSION_STATE_ESTABLISHED
132 The coap_session_get_state() function is used to get the current state
134 of the session.
135 OpenSSL: SSL*
137 GnuTLS: gnutls_session_t (implicit *)
138 Mbed TLS: mbedtls_ssl_context*
139 TinyDTLS: struct dtls_context*
140 The coap_session_get_tls() function is used to get the pointer to the
142 TLS information from the session. This is TLS library specific. tls_lib
143 is updated with the underlying (D)TLS library type.
144 COAP_SESSION_TYPE_CLIENT
146 COAP_SESSION_TYPE_SERVER
147 COAP_SESSION_TYPE_HELLO /* Negotiating a (D)TLS session */
148 The coap_session_get_type() function is used to get the session type
150 from the session.
151 The coap_session_get_psk_hint() function is used to get the current
153 server session's pre-shared-key identity hint.
154 The coap_session_get_psk_key() function is used to get the current
156 session's pre-shared-key key information.
157
159 coap_session_reference() function returns a pointer to the session.
160 coap_session_set_type_client() function returns 1 on success, otherwise
162 0.
163 coap_session_get_app_data() function return a previously defined
165 pointer.
166 coap_session_get_addr_local() and coap_session_get_addr_remote() return
168 a pointer to the IP address / port or NULL on error.
169 coap_session_get_context() returns a pointer to the current CoAP
171 Context or NULL on error.
172 coap_session_get_ifindex() returns the network interface the traffic
174 last came in over, or -1 on error.
175 coap_session_get_proto() returns the current session’s protocol or 0 on
177 error.
178 coap_session_get_state() returns the current session’s state or 0 on
180 error.
181 coap_session_get_tls() returns a pointer to the current session’s TLS
183 information (TLS library dependent) or NULL if there is none or there
184 is an error.
185 coap_session_get_type() returns the current session’s type or 0 on
187 error.
188 coap_session_get_psk_hint() returns the current server session’s
190 pre-shared-key identity hint, or NULL if not defined.
191 coap_session_get_psk_key() returns the current session’s pre-shared-key
193 key information, or NULL if not defined.
194
196 coap_context(3), coap_endpoint_client(3) and coap_endpoint_server(3)
197
199 See "RFC7252: The Constrained Application Protocol (CoAP)" for further
200 information.
201
203 Please report bugs on the mailing list for libcoap:
204 libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
205 https://github.com/obgm/libcoap/issues
206
208 The libcoap project <libcoap-developers@lists.sourceforge.net>
209coap_session 4.3.0 01/20/2022 COAP_SESSION(3)