coap_session_set_app_data(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_remote - Work with
10       CoAP sessions
11

SYNOPSIS

13       #include <coap3/coap.h>
14
15       coap_session_t *coap_session_reference(coap_session_t *session);
16
17       void coap_session_release(coap_session_t *session);
18
19       void coap_session_disconnected(coap_session_t *session,
20       coap_nack_reason_t reason);
21
22       int coap_session_set_type_client(coap_session_t *session);
23
24       void coap_session_set_app_data(coap_session_t *session, void *data);
25
26       void *coap_session_get_app_data(const coap_session_t *session);
27
28       const coap_address_t *coap_session_get_addr_local( const coap_session_t
29       *session);
30
31       const coap_address_t *coap_session_get_addr_remote( const
32       coap_session_t *session);
33
34       coap_context_t *coap_session_get_context(const coap_session_t
35       *session);
36
37       int coap_session_get_ifindex(const coap_session_t *session);
38
39       coap_proto_t coap_session_get_proto(const coap_session_t *session);
40
41       coap_session_state_t coap_session_get_state(const coap_session_t
42       *session);
43
44       void *coap_session_get_tls(const coap_session_t *session,
45       coap_tls_library_t *tls_lib);
46
47       coap_session_type_t coap_session_get_type(const coap_session_t
48       *session);
49
50       const coap_bin_const_t *coap_session_get_psk_hint( const coap_session_t
51       *session);
52
53       const coap_bin_const_t *coap_session_get_psk_key( const coap_session_t
54       *session);
55
56       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

DESCRIPTION

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
65       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
70       The Session network traffic can be encrypted or un-encrypted if there
71       is an underlying TLS library.
72
73       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
78       The coap_session_release() function is be used to decrement the session
79       reference count, which when it gets to 0, will:-
80
81       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
85       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
91       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
95       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
101       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
104       The coap_session_get_app_data() function is used to retrieve the data
105       pointer previously defined by coap_session_set_app_data().
106
107       The coap_session_get_addr_local() function is used to get the local IP
108       address and port information from the session.
109
110       The coap_session_get_addr_remote() function is used to get the remote
111       (peer) IP address and port information from the session.
112
113       The coap_session_get_context() function is used to get the CoAP context
114       associated with the session.
115
116       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
119           COAP_PROTO_UDP
120           COAP_PROTO_DTLS
121           COAP_PROTO_TCP
122           COAP_PROTO_TLS
123
124       The coap_session_get_proto() function is used to get the CoAP protocol
125       from the session.
126
127           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
133       The coap_session_get_state() function is used to get the current state
134       of the session.
135
136           OpenSSL:  SSL*
137           GnuTLS:   gnutls_session_t (implicit *)
138           Mbed TLS: mbedtls_ssl_context*
139           TinyDTLS: struct dtls_context*
140
141       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
145           COAP_SESSION_TYPE_CLIENT
146           COAP_SESSION_TYPE_SERVER
147           COAP_SESSION_TYPE_HELLO  /* Negotiating a (D)TLS session */
148
149       The coap_session_get_type() function is used to get the session type
150       from the session.
151
152       The coap_session_get_psk_hint() function is used to get the current
153       server session's pre-shared-key identity hint.
154
155       The coap_session_get_psk_key() function is used to get the current
156       session's pre-shared-key key information.
157

RETURN VALUES

159       coap_session_reference() function returns a pointer to the session.
160
161       coap_session_set_type_client() function returns 1 on success, otherwise
162       0.
163
164       coap_session_get_app_data() function return a previously defined
165       pointer.
166
167       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
170       coap_session_get_context() returns a pointer to the current CoAP
171       Context or NULL on error.
172
173       coap_session_get_ifindex() returns the network interface the traffic
174       last came in over, or -1 on error.
175
176       coap_session_get_proto() returns the current session’s protocol or 0 on
177       error.
178
179       coap_session_get_state() returns the current session’s state or 0 on
180       error.
181
182       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
186       coap_session_get_type() returns the current session’s type or 0 on
187       error.
188
189       coap_session_get_psk_hint() returns the current server session’s
190       pre-shared-key identity hint, or NULL if not defined.
191
192       coap_session_get_psk_key() returns the current session’s pre-shared-key
193       key information, or NULL if not defined.
194

FURTHER INFORMATION

199       See "RFC7252: The Constrained Application Protocol (CoAP)" for further
200       information.
201

BUGS

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

AUTHORS

208       The libcoap project <libcoap-developers@lists.sourceforge.net>
209
210
211
212coap_session 4.3.0                01/20/2022                   COAP_SESSION(3)