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  */
67  LCCSCF_MUXABLE_STREAM = (1 << 17),
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 */
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 */
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 */
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 
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  */
261 LWS_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  */
289 LWS_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  */
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
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
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 ///@}