coap_session(3)

1COAP_SESSION(3)                 libcoap Manual                 COAP_SESSION(3)
2
3
4

NAME

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_mcast,
10       coap_session_get_addr_remote, coap_session_get_context,
11       coap_session_get_ifindex, coap_session_get_proto,
12       coap_session_get_state, coap_session_get_tls, coap_session_get_type,
13       coap_session_get_psk_hint, coap_session_get_psk_key - Work with CoAP
14       sessions
15

SYNOPSIS

17       #include <coap3/coap.h>
18
19       coap_session_t *coap_session_reference(coap_session_t *session);
20
21       void coap_session_release(coap_session_t *session);
22
23       void coap_session_disconnected(coap_session_t *session,
24       coap_nack_reason_t reason);
25
26       int coap_session_set_type_client(coap_session_t *session);
27
28       void coap_session_set_app_data(coap_session_t *session, void *data);
29
30       void *coap_session_get_app_data(const coap_session_t *session);
31
32       const coap_address_t *coap_session_get_addr_local( const coap_session_t
33       *session);
34
35       const coap_address_t *coap_session_get_addr_mcast( const coap_session_t
36       *session);
37
38       const coap_address_t *coap_session_get_addr_remote( const
39       coap_session_t *session);
40
41       coap_context_t *coap_session_get_context(const coap_session_t
42       *session);
43
44       int coap_session_get_ifindex(const coap_session_t *session);
45
46       coap_proto_t coap_session_get_proto(const coap_session_t *session);
47
48       coap_session_state_t coap_session_get_state(const coap_session_t
49       *session);
50
51       void *coap_session_get_tls(const coap_session_t *session,
52       coap_tls_library_t *tls_lib);
53
54       coap_session_type_t coap_session_get_type(const coap_session_t
55       *session);
56
57       const coap_bin_const_t *coap_session_get_psk_hint( const coap_session_t
58       *session);
59
60       const coap_bin_const_t *coap_session_get_psk_key( const coap_session_t
61       *session);
62
63       For specific (D)TLS library support, link with -lcoap-3-notls,
64       -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or
65       -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default
66       (D)TLS library support.
67

DESCRIPTION

69       This man page focuses on the CoAP Session and how to update or get
70       information from the opaque coap_session_t structure.
71
72       A CoAP Session maintains the state of an ongoing connection between a
73       Client and Server which is stored in a coap_session_t Session object. A
74       CoAP session is tracked by local port, CoAP protocol, remote IP address
75       and remote port.
76
77       The Session network traffic can be encrypted or un-encrypted if there
78       is an underlying TLS library.
79

FUNCTIONS

81       Function: coap_session_reference()
82
83       The coap_session_reference() function is used to increment the
84       reference count of the session. Incrementing the reference count by an
85       application means that the library will not inadvertently remove the
86       session when it has finished processing the session.
87
88       Function: coap_session_release()
89
90       The coap_session_release() function is be used to decrement the session
91       reference count, which when it gets to 0, will:-
92
93       If type Client, free off the session which then clears all entries from
94       the receive queue and send queue. NOTE: All client sessions start off
95       with a reference count of 1.
96
97       If type Server, then the session is added to an idle pool ready for
98       subsequent re-use. If the Server session is not used for 5 minutes,
99       then it will get completely freed off. NOTE: Unless the application
100       increments the reference count, this is the case for all type server
101       sessions as they start with a reference count of 0.
102
103       Function: coap_session_disconnected()
104
105       The coap_session_disconnected() function is used to force the closure
106       of a session for the reason reason. It will cause any outstanding
107       traffic to get dropped.
108
109       Function: coap_session_set_type_client()
110
111       The coap_session_set_type_client() function is used to convert the
112       session frrm a session endpoint type of Server to Client. This
113       typically is used in a Call-Home type environment where the roles have
114       to change following the establishment of a session. The reference count
115       is incremented by 1.
116
117       Function: coap_session_set_app_data()
118
119       The coap_session_set_app_data() function is used to define a data
120       pointer for the session which can then be retrieved at a later date.
121
122       Function: coap_session_get_app_data()
123
124       The coap_session_get_app_data() function is used to retrieve the data
125       pointer previously defined by coap_session_set_app_data().
126
127       Function: coap_session_get_addr_local()
128
129       The coap_session_get_addr_local() function is used to get the local IP
130       address and port information from the session.
131
132       Function: coap_session_get_addr_mcast()
133
134       The coap_session_get_addr_mcast() function is used to get the remote
135       (peer) multicast IP address and port information from the session if
136       the session was originally set up to send requests to a multicast IP.
137
138       Function: coap_session_get_addr_remote()
139
140       The coap_session_get_addr_remote() function is used to get the remote
141       (peer) IP address and port information from the session. If the session
142       was originally set up to send requests to a multicast IP, then the
143       returned IP will be that of the unicast response from a peer. The
144       returned IP will get set back to the multicast IP when the next
145       coap_send(3) is called.
146
147       Function: coap_session_get_context()
148
149       The coap_session_get_context() function is used to get the CoAP context
150       associated with the session.
151
152       Function: coap_session_get_ifindex()
153
154       The coap_session_get_ifindex() function is used to get the network
155       interface index that the traffic came in over from the session.
156
157           COAP_PROTO_UDP
158           COAP_PROTO_DTLS
159           COAP_PROTO_TCP
160           COAP_PROTO_TLS
161           COAP_PROTO_WS
162           COAP_PROTO_WSS
163
164       The coap_session_get_proto() function is used to get the CoAP protocol
165       from the session.
166
167           COAP_SESSION_STATE_NONE
168           COAP_SESSION_STATE_CONNECTING
169           COAP_SESSION_STATE_HANDSHAKE
170           COAP_SESSION_STATE_CSM
171           COAP_SESSION_STATE_ESTABLISHED
172
173       The coap_session_get_state() function is used to get the current state
174       of the session.
175
176           OpenSSL:  SSL*
177           GnuTLS:   gnutls_session_t (implicit *)
178           Mbed TLS: mbedtls_ssl_context*
179           TinyDTLS: struct dtls_context*
180
181       The coap_session_get_tls() function is used to get the pointer to the
182       TLS information from the session. This is TLS library specific. tls_lib
183       is updated with the underlying (D)TLS library type.
184
185           COAP_SESSION_TYPE_CLIENT
186           COAP_SESSION_TYPE_SERVER
187           COAP_SESSION_TYPE_HELLO  /* Negotiating a (D)TLS session */
188
189       The coap_session_get_type() function is used to get the session type
190       from the session.
191
192       The coap_session_get_psk_hint() function is used to get the current
193       server session's pre-shared-key identity hint.
194
195       The coap_session_get_psk_key() function is used to get the current
196       session's pre-shared-key key information.
197

RETURN VALUES

199       coap_session_reference() returns a pointer to the session.
200
201       coap_session_set_type_client() returns 1 on success, otherwise 0.
202
203       coap_session_get_app_data() returns a previously defined pointer.
204
205       coap_session_get_addr_local() and coap_session_get_addr_remote() return
206       a pointer to the IP address / port or NULL on error.
207
208       coap_session_get_addr_mcast() returns a pointer to the remote multicast
209       IP address / port or NULL on error or this is not a multicast session.
210
211       coap_session_get_context() returns a pointer to the current CoAP
212       Context or NULL on error.
213
214       coap_session_get_ifindex() returns the network interface the traffic
215       last came in over, or -1 on error.
216
217       coap_session_get_proto() returns the current session’s protocol or 0 on
218       error.
219
220       coap_session_get_state() returns the current session’s state or 0 on
221       error.
222
223       coap_session_get_tls() returns a pointer to the current session’s TLS
224       information (TLS library dependent) or NULL if there is none or there
225       is an error.
226
227       coap_session_get_type() returns the current session’s type or 0 on
228       error.
229
230       coap_session_get_psk_hint() returns the current server session’s
231       pre-shared-key identity hint, or NULL if not defined.
232
233       coap_session_get_psk_key() returns the current session’s pre-shared-key
234       key information, or NULL if not defined.
235

FURTHER INFORMATION

240       See
241
242       "RFC7252: The Constrained Application Protocol (CoAP)"
243
244       for further information.
245

BUGS

247       Please report bugs on the mailing list for libcoap:
248       libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
249       https://github.com/obgm/libcoap/issues
250

AUTHORS

252       The libcoap project <libcoap-developers@lists.sourceforge.net>
253
254
255
256coap_session 4.3.4                10/09/2023                   COAP_SESSION(3)