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