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
38 LCCSCF_USE_SSL = (1 << 0),
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 */
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 */
85 /**< client is a link between SS client and SS proxy */
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 */
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 */
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
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 */
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 */
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 */
169 /**< 0 to pick an ephemeral port, or a specific local port
170 * to bind the socket to */
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
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
193 /**< optional retry and idle policy to apply to this connection.
194 * Currently only the idle parts are applied to the connection.
195 */
196
198 /**< if LCCSCF_H2_MANUAL_REFLOW is set, this becomes the initial tx
199 * credit for the stream.
200 */
201
203 /**< 0 means no client cert. 1+ means apply lws_system client cert 0+
204 * to the client connection.
205 */
206
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)
216#else
217 void *mqtt_cp;
218#endif
219
220#if defined(LWS_WITH_SYS_FAULT_INJECTION)
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
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
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 */
261LWS_VISIBLE LWS_EXTERN struct lws *
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 */
289LWS_VISIBLE LWS_EXTERN int
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 */
312LWS_VISIBLE LWS_EXTERN int
313lws_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 */
327LWS_VISIBLE LWS_EXTERN unsigned int
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 */
341LWS_VISIBLE LWS_EXTERN int
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 */
364LWS_VISIBLE LWS_EXTERN void
365lws_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 */
381LWS_VISIBLE LWS_EXTERN int
382lws_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 */
398LWS_VISIBLE LWS_EXTERN int
399lws_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 */
415LWS_VISIBLE LWS_EXTERN int
417
418///@}
const char * uri_replace_from
Definition: lws-client.h:147
struct lws ** pwsi
Definition: lws-client.h:154
const lws_retry_bo_t * retry_and_idle_policy
Definition: lws-client.h:192
lws_log_cx_t * log_cx
Definition: lws-client.h:237
const char * fi_wsi_name
Definition: lws-client.h:226
struct lws_vhost * vhost
Definition: lws-client.h:152
struct lws * parent_wsi
Definition: lws-client.h:143
const char * uri_replace_to
Definition: lws-client.h:150
const char * address
Definition: lws-client.h:117
const void * client_exts
Definition: lws-client.h:136
const char * protocol
Definition: lws-client.h:130
const char * local_protocol_name
Definition: lws-client.h:171
struct lws_context * context
Definition: lws-client.h:115
LWS_VISIBLE LWS_EXTERN void lws_client_http_body_pending(struct lws *wsi, int something_left_to_send)
LWS_VISIBLE LWS_EXTERN int lws_tls_session_is_reused(struct lws *wsi)
LWS_VISIBLE LWS_EXTERN int lws_http_basic_auth_gen(const char *user, const char *pw, char *buf, size_t len)
LWS_VISIBLE LWS_EXTERN int lws_http_client_read(struct lws *wsi, char **buf, int *len)
LWS_VISIBLE LWS_EXTERN int lws_client_http_multipart(struct lws *wsi, const char *name, const char *filename, const char *content_type, char **p, char *end)
LWS_VISIBLE LWS_EXTERN int lws_init_vhost_client_ssl(const struct lws_context_creation_info *info, struct lws_vhost *vhost)
LWS_VISIBLE LWS_EXTERN unsigned int lws_http_client_http_response(struct lws *wsi)
LWS_VISIBLE LWS_EXTERN struct lws * lws_client_connect_via_info(const struct lws_client_connect_info *ccinfo)
lws_client_connect_ssl_connection_flags
Definition: lws-client.h:37
LWS_VISIBLE LWS_EXTERN int lws_tls_client_vhost_extra_cert_mem(struct lws_vhost *vh, const uint8_t *der, size_t der_len)
@ LCCSCF_SECSTREAM_CLIENT
Definition: lws-client.h:82
@ LCCSCF_CACHE_COOKIES
Definition: lws-client.h:106
@ LCCSCF_HTTP_MULTIPART_MIME
Definition: lws-client.h:48
@ LCCSCF_HTTP_X_WWW_FORM_URLENCODED
Definition: lws-client.h:49
@ LCCSCF_IP_HIGH_RELIABILITY
Definition: lws-client.h:94
@ LCCSCF_CONMON
Definition: lws-client.h:100
@ LCCSCF_IP_LOW_LATENCY
Definition: lws-client.h:89
@ LCCSCF_IP_HIGH_THROUGHPUT
Definition: lws-client.h:91
@ LCCSCF_ALLOW_EXPIRED
Definition: lws-client.h:41
@ LCCSCF_ALLOW_REUSE_ADDR
Definition: lws-client.h:53
@ LCCSCF_H2_QUIRK_OVERFLOWS_TXCR
Definition: lws-client.h:44
@ LCCSCF_H2_MANUAL_RXFLOW
Definition: lws-client.h:47
@ LCCSCF_H2_QUIRK_NGHTTP2_END_STREAM
Definition: lws-client.h:43
@ LCCSCF_SECSTREAM_PROXY_LINK
Definition: lws-client.h:84
@ LCCSCF_USE_SSL
Definition: lws-client.h:38
@ LCCSCF_H2_PRIOR_KNOWLEDGE
Definition: lws-client.h:68
@ LCCSCF_PIPELINE
Definition: lws-client.h:59
@ LCCSCF_ALLOW_INSECURE
Definition: lws-client.h:42
@ LCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK
Definition: lws-client.h:40
@ LCCSCF_H2_AUTH_BEARER
Definition: lws-client.h:45
@ LCCSCF_WAKE_SUSPEND__VALIDITY
Definition: lws-client.h:69
@ LCCSCF_ACCEPT_TLS_DOWNGRADE_REDIRECTS
Definition: lws-client.h:103
@ LCCSCF_HTTP_NO_FOLLOW_REDIRECT
Definition: lws-client.h:50
@ LCCSCF_SECSTREAM_PROXY_ONWARD
Definition: lws-client.h:86
@ LCCSCF_PRIORITIZE_READS
Definition: lws-client.h:71
@ LCCSCF_IP_LOW_COST
Definition: lws-client.h:97
@ LCCSCF_HTTP_NO_CACHE_CONTROL
Definition: lws-client.h:51
@ LCCSCF_H2_HEXIFY_AUTH_TOKEN
Definition: lws-client.h:46
@ LCCSCF_MUXABLE_STREAM
Definition: lws-client.h:67
@ LCCSCF_ALLOW_SELFSIGNED
Definition: lws-client.h:39