libwebsockets
Lightweight C library for HTML5 websockets
lws-client.h
Go to the documentation of this file.
1
/*
2
* libwebsockets - small server side websockets and web server implementation
3
*
4
* Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
5
*
6
* Permission is hereby granted, free of charge, to any person obtaining a copy
7
* of this software and associated documentation files (the "Software"), to
8
* deal in the Software without restriction, including without limitation the
9
* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10
* sell copies of the Software, and to permit persons to whom the Software is
11
* furnished to do so, subject to the following conditions:
12
*
13
* The above copyright notice and this permission notice shall be included in
14
* all copies or substantial portions of the Software.
15
*
16
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22
* IN THE SOFTWARE.
23
*/
24
25
/*! \defgroup client Client related functions
26
* ##Client releated functions
27
* \ingroup lwsapi
28
*
29
* */
30
///@{
31
32
/** enum lws_client_connect_ssl_connection_flags - flags that may be used
33
* with struct lws_client_connect_info ssl_connection member to control if
34
* and how SSL checks apply to the client connection being created
35
*/
36
37
enum
lws_client_connect_ssl_connection_flags
{
38
LCCSCF_USE_SSL
= (1 << 0),
39
LCCSCF_ALLOW_SELFSIGNED
= (1 << 1),
40
LCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK
= (1 << 2),
41
LCCSCF_ALLOW_EXPIRED
= (1 << 3),
42
LCCSCF_ALLOW_INSECURE
= (1 << 4),
43
LCCSCF_H2_QUIRK_NGHTTP2_END_STREAM
= (1 << 5),
44
LCCSCF_H2_QUIRK_OVERFLOWS_TXCR
= (1 << 6),
45
LCCSCF_H2_AUTH_BEARER
= (1 << 7),
46
LCCSCF_H2_HEXIFY_AUTH_TOKEN
= (1 << 8),
47
LCCSCF_H2_MANUAL_RXFLOW
= (1 << 9),
48
LCCSCF_HTTP_MULTIPART_MIME
= (1 << 10),
49
LCCSCF_HTTP_X_WWW_FORM_URLENCODED
= (1 << 11),
50
LCCSCF_HTTP_NO_FOLLOW_REDIRECT
= (1 << 12),
51
LCCSCF_HTTP_NO_CACHE_CONTROL
= (1 << 13),
52
53
LCCSCF_ALLOW_REUSE_ADDR
= (1 << 14),
54
/**< allow reuse local addresses in a bind call
55
* When the listening socket is bound to INADDR_ANY with a specific port
56
* then it is not possible to bind to this port for any local address
57
*/
58
59
LCCSCF_PIPELINE
= (1 << 16),
60
/**< Serialize / pipeline multiple client connections
61
* on a single connection where possible.
62
*
63
* HTTP/1.0: possible if Keep-Alive: yes sent by server
64
* HTTP/1.1: always possible... uses pipelining
65
* HTTP/2: always possible... uses parallel streams
66
*/
67
LCCSCF_MUXABLE_STREAM
= (1 << 17),
68
LCCSCF_H2_PRIOR_KNOWLEDGE
= (1 << 18),
69
LCCSCF_WAKE_SUSPEND__VALIDITY
= (1 << 19),
70
/* our validity checks are important enough to wake from suspend */
71
LCCSCF_PRIORITIZE_READS
= (1 << 20),
72
/**<
73
* Normally lws balances reads and writes on all connections, so both
74
* are possible even on busy connections, and we go around the event
75
* loop more often to facilitate that, even if there is pending data.
76
*
77
* This flag indicates that you want to handle any pending reads on this
78
* connection without yielding the service loop for anything else. This
79
* means you may block other connection processing in favour of incoming
80
* data processing on this one if it receives back to back incoming rx.
81
*/
82
LCCSCF_SECSTREAM_CLIENT
= (1 << 21),
83
/**< used to mark client wsi as bound to secure stream */
84
LCCSCF_SECSTREAM_PROXY_LINK
= (1 << 22),
85
/**< client is a link between SS client and SS proxy */
86
LCCSCF_SECSTREAM_PROXY_ONWARD
= (1 << 23),
87
/**< client the SS proxy's onward connection */
88
89
LCCSCF_IP_LOW_LATENCY
= (1 << 24),
90
/**< set the "low delay" bit on the IP packets of this connection */
91
LCCSCF_IP_HIGH_THROUGHPUT
= (1 << 25),
92
/**< set the "high throughput" bit on the IP packets of this
93
* connection */
94
LCCSCF_IP_HIGH_RELIABILITY
= (1 << 26),
95
/**< set the "high reliability" bit on the IP packets of this
96
* connection */
97
LCCSCF_IP_LOW_COST
= (1 << 27),
98
/**< set the "minimize monetary cost" bit on the IP packets of this
99
* connection */
100
LCCSCF_CONMON
= (1 << 28),
101
/**< If LWS_WITH_CONMON enabled for build, keeps a copy of the
102
* getaddrinfo results so they can be queried subsequently */
103
LCCSCF_ACCEPT_TLS_DOWNGRADE_REDIRECTS
= (1 << 29),
104
/**< By default lws rejects https redirecting to http. Set this
105
* flag on the client connection to allow it. */
106
LCCSCF_CACHE_COOKIES
= (1 << 30),
107
/**< If built with -DLWS_WITH_CACHE_NSCOOKIEJAR, store and reapply
108
* http cookies in a Netscape Cookie Jar on this connection */
109
};
110
111
/** struct lws_client_connect_info - parameters to connect with when using
112
* lws_client_connect_via_info() */
113
114
struct
lws_client_connect_info
{
115
struct
lws_context *
context
;
116
/**< lws context to create connection in */
117
const
char
*
address
;
118
/**< remote address to connect to */
119
int
port
;
120
/**< remote port to connect to */
121
int
ssl_connection
;
122
/**< 0, or a combination of LCCSCF_ flags */
123
const
char
*
path
;
124
/**< URI path. Prefix with + for a UNIX socket. (+@ for
125
* a Linux abstract-namespace socket) */
126
const
char
*
host
;
127
/**< content of host header */
128
const
char
*
origin
;
129
/**< content of origin header */
130
const
char
*
protocol
;
131
/**< list of ws protocols we could accept */
132
int
ietf_version_or_minus_one
;
133
/**< deprecated: currently leave at 0 or -1 */
134
void
*
userdata
;
135
/**< if non-NULL, use this as wsi user_data instead of malloc it */
136
const
void
*
client_exts
;
137
/**< UNUSED... provide in info.extensions at context creation time */
138
const
char
*
method
;
139
/**< if non-NULL, do this http method instead of ws[s] upgrade.
140
* use "GET" to be a simple http client connection. "RAW" gets
141
* you a connected socket that lws itself will leave alone once
142
* connected. */
143
struct
lws *
parent_wsi
;
144
/**< if another wsi is responsible for this connection, give it here.
145
* this is used to make sure if the parent closes so do any
146
* child connections first. */
147
const
char
*
uri_replace_from
;
148
/**< if non-NULL, when this string is found in URIs in
149
* text/html content-encoding, it's replaced with uri_replace_to */
150
const
char
*
uri_replace_to
;
151
/**< see uri_replace_from */
152
struct
lws_vhost *
vhost
;
153
/**< vhost to bind to (used to determine related SSL_CTX) */
154
struct
lws **
pwsi
;
155
/**< if not NULL, store the new wsi here early in the connection
156
* process. Although we return the new wsi, the call to create the
157
* client connection does progress the connection somewhat and may
158
* meet an error that will result in the connection being scrubbed and
159
* NULL returned. While the wsi exists though, he may process a
160
* callback like CLIENT_CONNECTION_ERROR with his wsi: this gives the
161
* user callback a way to identify which wsi it is that faced the error
162
* even before the new wsi is returned and even if ultimately no wsi
163
* is returned.
164
*/
165
const
char
*
iface
;
166
/**< NULL to allow routing on any interface, or interface name or IP
167
* to bind the socket to */
168
int
local_port
;
169
/**< 0 to pick an ephemeral port, or a specific local port
170
* to bind the socket to */
171
const
char
*
local_protocol_name
;
172
/**< NULL: .protocol is used both to select the local protocol handler
173
* to bind to and as the list of remote ws protocols we could
174
* accept.
175
* non-NULL: this protocol name is used to bind the connection to
176
* the local protocol handler. .protocol is used for the
177
* list of remote ws protocols we could accept */
178
const
char
*
alpn
;
179
/**< NULL: allow lws default ALPN list, from vhost if present or from
180
* list of roles built into lws
181
* non-NULL: require one from provided comma-separated list of alpn
182
* tokens
183
*/
184
185
void
*
opaque_user_data
;
186
/**< This data has no meaning to lws but is applied to the client wsi
187
* and can be retrieved by user code with lws_get_opaque_user_data().
188
* It's also provided with sequencer messages if the wsi is bound to
189
* an lws_seq_t.
190
*/
191
192
const
lws_retry_bo_t
*
retry_and_idle_policy
;
193
/**< optional retry and idle policy to apply to this connection.
194
* Currently only the idle parts are applied to the connection.
195
*/
196
197
int
manual_initial_tx_credit
;
198
/**< if LCCSCF_H2_MANUAL_REFLOW is set, this becomes the initial tx
199
* credit for the stream.
200
*/
201
202
uint8_t
sys_tls_client_cert
;
203
/**< 0 means no client cert. 1+ means apply lws_system client cert 0+
204
* to the client connection.
205
*/
206
207
uint8_t
priority
;
208
/**< 0 means normal priority... otherwise sets the IP priority on
209
* packets coming from this connection, from 1 - 7. Setting 7
210
* (network management priority) requires CAP_NET_ADMIN capability but
211
* the others can be set by anyone.
212
*/
213
214
#
if
defined
(
LWS_ROLE_MQTT
)
215
const
lws_mqtt_client_connect_param_t
*
mqtt_cp
;
216
#
else
217
void
*
mqtt_cp
;
218
#
endif
219
220
#
if
defined
(
LWS_WITH_SYS_FAULT_INJECTION
)
221
lws_fi_ctx_t
fic
;
222
/**< Attach external Fault Injection context to the client wsi,
223
* hierarchy is wsi -> vhost -> context */
224
#
endif
225
/* for convenience, available when FI disabled in build */
226
const
char
*
fi_wsi_name
;
227
/**< specific Fault Injection namespace name for wsi created for this
228
* connection, allows targeting by "wsi=XXX/..." if you give XXX here.
229
*/
230
231
uint16_t
keep_warm_secs
;
232
/**< 0 means 5s. If the client connection to the endpoint becomes idle,
233
* defer closing it for this many seconds in case another outgoing
234
* connection to the same endpoint turns up.
235
*/
236
237
lws_log_cx_t
*
log_cx
;
238
/**< NULL to use lws_context log context, else a pointer to a log
239
* context template to take a copy of for this wsi. Used to isolate
240
* wsi-specific logs into their own stream or file.
241
*/
242
243
/* Add new things just above here ---^
244
* This is part of the ABI, don't needlessly break compatibility
245
*
246
* The below is to ensure later library versions with new
247
* members added above will see 0 (default) even if the app
248
* was not built against the newer headers.
249
*/
250
251
void
*
_unused
[4];
/**< dummy */
252
};
253
254
/**
255
* lws_client_connect_via_info() - Connect to another websocket server
256
* \param ccinfo: pointer to lws_client_connect_info struct
257
*
258
* This function creates a connection to a remote server using the
259
* information provided in ccinfo.
260
*/
261
LWS_VISIBLE LWS_EXTERN
struct
lws *
262
lws_client_connect_via_info
(
const
struct
lws_client_connect_info
*ccinfo);
263
264
/**
265
* lws_init_vhost_client_ssl() - also enable client SSL on an existing vhost
266
*
267
* \param info: client ssl related info
268
* \param vhost: which vhost to initialize client ssl operations on
269
*
270
* You only need to call this if you plan on using SSL client connections on
271
* the vhost. For non-SSL client connections, it's not necessary to call this.
272
*
273
* The following members of info are used during the call
274
*
275
* - options must have LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT set,
276
* otherwise the call does nothing
277
* - provided_client_ssl_ctx must be NULL to get a generated client
278
* ssl context, otherwise you can pass a prepared one in by setting it
279
* - ssl_cipher_list may be NULL or set to the client valid cipher list
280
* - ssl_ca_filepath may be NULL or client cert filepath
281
* - ssl_cert_filepath may be NULL or client cert filepath
282
* - ssl_private_key_filepath may be NULL or client cert private key
283
*
284
* You must create your vhost explicitly if you want to use this, so you have
285
* a pointer to the vhost. Create the context first with the option flag
286
* LWS_SERVER_OPTION_EXPLICIT_VHOSTS and then call lws_create_vhost() with
287
* the same info struct.
288
*/
289
LWS_VISIBLE LWS_EXTERN
int
290
lws_init_vhost_client_ssl
(
const
struct
lws_context_creation_info
*info,
291
struct
lws_vhost *vhost);
292
/**
293
* lws_http_client_read() - consume waiting received http client data
294
*
295
* \param wsi: client connection
296
* \param buf: pointer to buffer pointer - fill with pointer to your buffer
297
* \param len: pointer to chunk length - fill with max length of buffer
298
*
299
* This is called when the user code is notified client http data has arrived.
300
* The user code may choose to delay calling it to consume the data, for example
301
* waiting until an onward connection is writeable.
302
*
303
* For non-chunked connections, up to len bytes of buf are filled with the
304
* received content. len is set to the actual amount filled before return.
305
*
306
* For chunked connections, the linear buffer content contains the chunking
307
* headers and it cannot be passed in one lump. Instead, this function will
308
* call back LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ with in pointing to the
309
* chunk start and len set to the chunk length. There will be as many calls
310
* as there are chunks or partial chunks in the buffer.
311
*/
312
LWS_VISIBLE LWS_EXTERN
int
313
lws_http_client_read
(
struct
lws *wsi,
char
**buf,
int
*len);
314
315
/**
316
* lws_http_client_http_response() - get last HTTP response code
317
*
318
* \param wsi: client connection
319
*
320
* Returns the last server response code, eg, 200 for client http connections.
321
* If there is no valid response, it will return 0.
322
*
323
* You should capture this during the LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP
324
* callback, because after that the memory reserved for storing the related
325
* headers is freed and this value is lost.
326
*/
327
LWS_VISIBLE LWS_EXTERN
unsigned
int
328
lws_http_client_http_response
(
struct
lws *wsi);
329
330
/**
331
* lws_tls_client_vhost_extra_cert_mem() - add more certs to vh client tls ctx
332
*
333
* \param vh: the vhost to give more client certs to
334
* \param der: pointer to der format additional cert
335
* \param der_len: size in bytes of der
336
*
337
* After the vhost is created with one cert for client verification, you
338
* can add additional, eg, intermediate, certs to the client tls context
339
* of the vhost, for use with validating the incoming server cert(s).
340
*/
341
LWS_VISIBLE LWS_EXTERN
int
342
lws_tls_client_vhost_extra_cert_mem
(
struct
lws_vhost *vh,
343
const
uint8_t *der, size_t der_len);
344
345
/**
346
* lws_client_http_body_pending() - control if client connection needs to send body
347
*
348
* \param wsi: client connection
349
* \param something_left_to_send: nonzero if need to send more body, 0 (default)
350
* if nothing more to send
351
*
352
* If you will send payload data with your HTTP client connection, eg, for POST,
353
* when you set the related http headers in
354
* LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER callback you should also call
355
* this API with something_left_to_send nonzero, and call
356
* lws_callback_on_writable(wsi);
357
*
358
* After sending the headers, lws will call your callback with
359
* LWS_CALLBACK_CLIENT_HTTP_WRITEABLE reason when writable. You can send the
360
* next part of the http body payload, calling lws_callback_on_writable(wsi);
361
* if there is more to come, or lws_client_http_body_pending(wsi, 0); to
362
* let lws know the last part is sent and the connection can move on.
363
*/
364
LWS_VISIBLE LWS_EXTERN
void
365
lws_client_http_body_pending
(
struct
lws *wsi,
int
something_left_to_send);
366
367
/**
368
* lws_client_http_multipart() - issue appropriate multipart header or trailer
369
*
370
* \param wsi: client connection
371
* \param name: multipart header name field, or NULL if end of multipart
372
* \param filename: multipart header filename field, or NULL if none
373
* \param content_type: multipart header content-type part, or NULL if none
374
* \param p: pointer to position in buffer
375
* \param end: end of buffer
376
*
377
* This issues a multipart mime boundary, or terminator if name = NULL.
378
*
379
* Returns 0 if OK or nonzero if couldn't fit in buffer
380
*/
381
LWS_VISIBLE LWS_EXTERN
int
382
lws_client_http_multipart
(
struct
lws *wsi,
const
char
*name,
383
const
char
*filename,
const
char
*content_type,
384
char
**p,
char
*end);
385
386
/**
387
* lws_http_basic_auth_gen() - helper to encode client basic auth string
388
*
389
* \param user: user name
390
* \param pw: password
391
* \param buf: where to store base64 result
392
* \param len: max usable size of buf
393
*
394
* Encodes a username and password in Basic Auth format for use with the
395
* Authorization header. On return, buf is filled with something like
396
* "Basic QWxhZGRpbjpPcGVuU2VzYW1l".
397
*/
398
LWS_VISIBLE LWS_EXTERN
int
399
lws_http_basic_auth_gen
(
const
char
*user,
const
char
*pw,
char
*buf, size_t len);
400
401
/**
402
* lws_tls_session_is_reused() - returns nonzero if tls session was cached
403
*
404
* \param wsi: the wsi
405
*
406
* Returns zero if the tls session is fresh, else nonzero if the tls session was
407
* taken from the cache. If lws is built with LWS_WITH_TLS_SESSIONS and the vhost
408
* was created with the option LWS_SERVER_OPTION_ENABLE_TLS_SESSION_CACHE, then
409
* on full tls session establishment of a client connection, the session is added
410
* to the tls cache.
411
*
412
* This lets you find out if your session was new (0) or from the cache (nonzero),
413
* it'a mainly useful for stats and testing.
414
*/
415
LWS_VISIBLE LWS_EXTERN
int
416
lws_tls_session_is_reused
(
struct
lws *wsi);
417
418
///@}
include
libwebsockets
lws-client.h
Generated on Fri Jun 17 2022 04:56:33 for libwebsockets by
1.9.1