libwebsockets
Lightweight C library for HTML5 websockets
Client related functions

Data Structures

struct  lws_client_connect_info
 

Enumerations

enum  lws_client_connect_ssl_connection_flags {
  LCCSCF_USE_SSL = (1 << 0) , LCCSCF_ALLOW_SELFSIGNED = (1 << 1) , LCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK = (1 << 2) , LCCSCF_ALLOW_EXPIRED = (1 << 3) ,
  LCCSCF_ALLOW_INSECURE = (1 << 4) , LCCSCF_H2_QUIRK_NGHTTP2_END_STREAM = (1 << 5) , LCCSCF_H2_QUIRK_OVERFLOWS_TXCR = (1 << 6) , LCCSCF_H2_AUTH_BEARER = (1 << 7) ,
  LCCSCF_H2_HEXIFY_AUTH_TOKEN = (1 << 8) , LCCSCF_H2_MANUAL_RXFLOW = (1 << 9) , LCCSCF_HTTP_MULTIPART_MIME = (1 << 10) , LCCSCF_HTTP_X_WWW_FORM_URLENCODED = (1 << 11) ,
  LCCSCF_HTTP_NO_FOLLOW_REDIRECT = (1 << 12) , LCCSCF_PIPELINE = (1 << 16) , LCCSCF_MUXABLE_STREAM = (1 << 17) , LCCSCF_H2_PRIOR_KNOWLEDGE = (1 << 18) ,
  LCCSCF_WAKE_SUSPEND__VALIDITY = (1 << 19) , LCCSCF_PRIORITIZE_READS = (1 << 20) , LCCSCF_SECSTREAM_CLIENT = (1 << 21) , LCCSCF_SECSTREAM_PROXY_LINK = (1 << 22) ,
  LCCSCF_SECSTREAM_PROXY_ONWARD = (1 << 23) , LCCSCF_IP_LOW_LATENCY = (1 << 24) , LCCSCF_IP_HIGH_THROUGHPUT = (1 << 25) , LCCSCF_IP_HIGH_RELIABILITY = (1 << 26) ,
  LCCSCF_IP_LOW_COST = (1 << 27) , LCCSCF_CONMON = (1 << 28) , LCCSCF_ACCEPT_TLS_DOWNGRADE_REDIRECTS = (1 << 29) , LCCSCF_CACHE_COOKIES = (1 << 30)
}
 

Functions

LWS_VISIBLE LWS_EXTERN struct lws * lws_client_connect_via_info (const struct lws_client_connect_info *ccinfo)
 
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 int lws_http_client_read (struct lws *wsi, char **buf, int *len)
 
LWS_VISIBLE LWS_EXTERN unsigned int lws_http_client_http_response (struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN int lws_tls_client_vhost_extra_cert_mem (struct lws_vhost *vh, const uint8_t *der, size_t der_len)
 
LWS_VISIBLE LWS_EXTERN void lws_client_http_body_pending (struct lws *wsi, int something_left_to_send)
 
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_http_basic_auth_gen (const char *user, const char *pw, char *buf, size_t len)
 
LWS_VISIBLE LWS_EXTERN int lws_tls_session_is_reused (struct lws *wsi)
 

Detailed Description

Client releated functions

Enumeration Type Documentation

◆ lws_client_connect_ssl_connection_flags

#include <include/libwebsockets/lws-client.h>

enum lws_client_connect_ssl_connection_flags - flags that may be used with struct lws_client_connect_info ssl_connection member to control if and how SSL checks apply to the client connection being created

Enumerator
LCCSCF_PIPELINE 

Serialize / pipeline multiple client connections on a single connection where possible.

HTTP/1.0: possible if Keep-Alive: yes sent by server HTTP/1.1: always possible... uses pipelining HTTP/2: always possible... uses parallel streams

LCCSCF_PRIORITIZE_READS 

Normally lws balances reads and writes on all connections, so both are possible even on busy connections, and we go around the event loop more often to facilitate that, even if there is pending data.

This flag indicates that you want to handle any pending reads on this connection without yielding the service loop for anything else. This means you may block other connection processing in favour of incoming data processing on this one if it receives back to back incoming rx.

LCCSCF_SECSTREAM_CLIENT 

used to mark client wsi as bound to secure stream

LCCSCF_SECSTREAM_PROXY_LINK 

client is a link between SS client and SS proxy

LCCSCF_SECSTREAM_PROXY_ONWARD 

client the SS proxy's onward connection

LCCSCF_IP_LOW_LATENCY 

set the "low delay" bit on the IP packets of this connection

LCCSCF_IP_HIGH_THROUGHPUT 

set the "high throughput" bit on the IP packets of this connection

LCCSCF_IP_HIGH_RELIABILITY 

set the "high reliability" bit on the IP packets of this connection

LCCSCF_IP_LOW_COST 

set the "minimize monetary cost" bit on the IP packets of this connection

LCCSCF_CONMON 

If LWS_WITH_CONMON enabled for build, keeps a copy of the getaddrinfo results so they can be queried subsequently

LCCSCF_ACCEPT_TLS_DOWNGRADE_REDIRECTS 

By default lws rejects https redirecting to http. Set this flag on the client connection to allow it.

LCCSCF_CACHE_COOKIES 

If built with -DLWS_WITH_CACHE_NSCOOKIEJAR, store and reapply http cookies in a Netscape Cookie Jar on this connection

37  {
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 
52  LCCSCF_PIPELINE = (1 << 16),
60  LCCSCF_MUXABLE_STREAM = (1 << 17),
61  LCCSCF_H2_PRIOR_KNOWLEDGE = (1 << 18),
62  LCCSCF_WAKE_SUSPEND__VALIDITY = (1 << 19),
63  /* our validity checks are important enough to wake from suspend */
64  LCCSCF_PRIORITIZE_READS = (1 << 20),
75  LCCSCF_SECSTREAM_CLIENT = (1 << 21),
77  LCCSCF_SECSTREAM_PROXY_LINK = (1 << 22),
82  LCCSCF_IP_LOW_LATENCY = (1 << 24),
84  LCCSCF_IP_HIGH_THROUGHPUT = (1 << 25),
87  LCCSCF_IP_HIGH_RELIABILITY = (1 << 26),
90  LCCSCF_IP_LOW_COST = (1 << 27),
93  LCCSCF_CONMON = (1 << 28),
99  LCCSCF_CACHE_COOKIES = (1 << 30),
102 };
@ LCCSCF_SECSTREAM_CLIENT
Definition: lws-client.h:75
@ LCCSCF_CACHE_COOKIES
Definition: lws-client.h:99
@ LCCSCF_IP_HIGH_RELIABILITY
Definition: lws-client.h:87
@ LCCSCF_CONMON
Definition: lws-client.h:93
@ LCCSCF_IP_LOW_LATENCY
Definition: lws-client.h:82
@ LCCSCF_IP_HIGH_THROUGHPUT
Definition: lws-client.h:84
@ LCCSCF_SECSTREAM_PROXY_LINK
Definition: lws-client.h:77
@ LCCSCF_PIPELINE
Definition: lws-client.h:52
@ LCCSCF_ACCEPT_TLS_DOWNGRADE_REDIRECTS
Definition: lws-client.h:96
@ LCCSCF_SECSTREAM_PROXY_ONWARD
Definition: lws-client.h:79
@ LCCSCF_PRIORITIZE_READS
Definition: lws-client.h:64
@ LCCSCF_IP_LOW_COST
Definition: lws-client.h:90

Function Documentation

◆ lws_client_connect_via_info()

LWS_VISIBLE LWS_EXTERN struct lws* lws_client_connect_via_info ( const struct lws_client_connect_info ccinfo)

#include <include/libwebsockets/lws-client.h>

lws_client_connect_via_info() - Connect to another websocket server

Parameters
ccinfopointer to lws_client_connect_info struct
 This function creates a connection to a remote server using the
 information provided in ccinfo.

◆ lws_client_http_body_pending()

LWS_VISIBLE LWS_EXTERN void lws_client_http_body_pending ( struct lws *  wsi,
int  something_left_to_send 
)

#include <include/libwebsockets/lws-client.h>

lws_client_http_body_pending() - control if client connection needs to send body

Parameters
wsiclient connection
something_left_to_sendnonzero if need to send more body, 0 (default) if nothing more to send

If you will send payload data with your HTTP client connection, eg, for POST, when you set the related http headers in LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER callback you should also call this API with something_left_to_send nonzero, and call lws_callback_on_writable(wsi);

After sending the headers, lws will call your callback with LWS_CALLBACK_CLIENT_HTTP_WRITEABLE reason when writable. You can send the next part of the http body payload, calling lws_callback_on_writable(wsi); if there is more to come, or lws_client_http_body_pending(wsi, 0); to let lws know the last part is sent and the connection can move on.

◆ lws_client_http_multipart()

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 
)

#include <include/libwebsockets/lws-client.h>

lws_client_http_multipart() - issue appropriate multipart header or trailer

Parameters
wsiclient connection
namemultipart header name field, or NULL if end of multipart
filenamemultipart header filename field, or NULL if none
content_typemultipart header content-type part, or NULL if none
ppointer to position in buffer
endend of buffer

This issues a multipart mime boundary, or terminator if name = NULL.

Returns 0 if OK or nonzero if couldn't fit in buffer

◆ lws_http_basic_auth_gen()

LWS_VISIBLE LWS_EXTERN int lws_http_basic_auth_gen ( const char *  user,
const char *  pw,
char *  buf,
size_t  len 
)

#include <include/libwebsockets/lws-client.h>

lws_http_basic_auth_gen() - helper to encode client basic auth string

Parameters
useruser name
pwpassword
bufwhere to store base64 result
lenmax usable size of buf

Encodes a username and password in Basic Auth format for use with the Authorization header. On return, buf is filled with something like "Basic QWxhZGRpbjpPcGVuU2VzYW1l".

◆ lws_http_client_http_response()

LWS_VISIBLE LWS_EXTERN unsigned int lws_http_client_http_response ( struct lws *  wsi)

#include <include/libwebsockets/lws-client.h>

lws_http_client_http_response() - get last HTTP response code

Parameters
wsiclient connection

Returns the last server response code, eg, 200 for client http connections.

You should capture this during the LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP callback, because after that the memory reserved for storing the related headers is freed and this value is lost.

◆ lws_http_client_read()

LWS_VISIBLE LWS_EXTERN int lws_http_client_read ( struct lws *  wsi,
char **  buf,
int *  len 
)

#include <include/libwebsockets/lws-client.h>

lws_http_client_read() - consume waiting received http client data

Parameters
wsiclient connection
bufpointer to buffer pointer - fill with pointer to your buffer
lenpointer to chunk length - fill with max length of buffer

This is called when the user code is notified client http data has arrived. The user code may choose to delay calling it to consume the data, for example waiting until an onward connection is writeable.

For non-chunked connections, up to len bytes of buf are filled with the received content. len is set to the actual amount filled before return.

For chunked connections, the linear buffer content contains the chunking headers and it cannot be passed in one lump. Instead, this function will call back LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ with in pointing to the chunk start and len set to the chunk length. There will be as many calls as there are chunks or partial chunks in the buffer.

◆ lws_init_vhost_client_ssl()

LWS_VISIBLE LWS_EXTERN int lws_init_vhost_client_ssl ( const struct lws_context_creation_info info,
struct lws_vhost *  vhost 
)

#include <include/libwebsockets/lws-client.h>

lws_init_vhost_client_ssl() - also enable client SSL on an existing vhost

Parameters
infoclient ssl related info
vhostwhich vhost to initialize client ssl operations on

You only need to call this if you plan on using SSL client connections on the vhost. For non-SSL client connections, it's not necessary to call this.

The following members of info are used during the call

  - options must have LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT set,
      otherwise the call does nothing
  - provided_client_ssl_ctx must be NULL to get a generated client
      ssl context, otherwise you can pass a prepared one in by setting it
  - ssl_cipher_list may be NULL or set to the client valid cipher list
  - ssl_ca_filepath may be NULL or client cert filepath
  - ssl_cert_filepath may be NULL or client cert filepath
  - ssl_private_key_filepath may be NULL or client cert private key

You must create your vhost explicitly if you want to use this, so you have a pointer to the vhost. Create the context first with the option flag LWS_SERVER_OPTION_EXPLICIT_VHOSTS and then call lws_create_vhost() with the same info struct.

◆ lws_tls_client_vhost_extra_cert_mem()

LWS_VISIBLE LWS_EXTERN int lws_tls_client_vhost_extra_cert_mem ( struct lws_vhost *  vh,
const uint8_t *  der,
size_t  der_len 
)

#include <include/libwebsockets/lws-client.h>

lws_tls_client_vhost_extra_cert_mem() - add more certs to vh client tls ctx

Parameters
vhthe vhost to give more client certs to
derpointer to der format additional cert
der_lensize in bytes of der

After the vhost is created with one cert for client verification, you can add additional, eg, intermediate, certs to the client tls context of the vhost, for use with validating the incoming server cert(s).

◆ lws_tls_session_is_reused()

LWS_VISIBLE LWS_EXTERN int lws_tls_session_is_reused ( struct lws *  wsi)

#include <include/libwebsockets/lws-client.h>

lws_tls_session_is_reused() - returns nonzero if tls session was cached

Parameters
wsithe wsi

Returns zero if the tls session is fresh, else nonzero if the tls session was taken from the cache. If lws is built with LWS_WITH_TLS_SESSIONS and the vhost was created with the option LWS_SERVER_OPTION_ENABLE_TLS_SESSION_CACHE, then on full tls session establishment of a client connection, the session is added to the tls cache.

This lets you find out if your session was new (0) or from the cache (nonzero), it'a mainly useful for stats and testing.