{"schema":"libjg2-1", "vpath":"/git/", "avatar":"/git/avatar/", "alang":"", "gen_ut":1751770963, "reponame":"libwebsockets", "desc":"libwebsockets lightweight C networking library", "owner": { "name": "Andy Green", "email": "andy@warmcat.com", "md5": "c50933ca2aa61e0fe2c43d46bb6b59cb" },"url":"https://libwebsockets.org/repo/libwebsockets", "f":3, "items": [ {"schema":"libjg2-1", "cid":"ebd2a448c4ee48c3f26ad7f4c65a45c5", "oid":{ "oid": "014535d746087a4758c67a88dc99e632d0e3c085", "alias": [ "refs/heads/main"]},"blobname": "include/libwebsockets/lws-client.h", "blob": "/*\n * libwebsockets - small server side websockets and web server implementation\n *\n * Copyright (C) 2010 - 2021 Andy Green \u003candy@warmcat.com\u003e\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \u0022Software\u0022), to\n * deal in the Software without restriction, including without limitation the\n * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or\n * sell copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in\n * all copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \u0022AS IS\u0022, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\n * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS\n * IN THE SOFTWARE.\n */\n\n/*! \u005cdefgroup client Client related functions\n * ##Client releated functions\n * \u005cingroup lwsapi\n *\n * */\n///@{\n\n/** enum lws_client_connect_ssl_connection_flags - flags that may be used\n * with struct lws_client_connect_info ssl_connection member to control if\n * and how SSL checks apply to the client connection being created\n */\n\nenum lws_client_connect_ssl_connection_flags {\n\tLCCSCF_USE_SSL \t\t\t\t\u003d (1 \u003c\u003c 0),\n\tLCCSCF_ALLOW_SELFSIGNED\t\t\t\u003d (1 \u003c\u003c 1),\n\tLCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK\t\u003d (1 \u003c\u003c 2),\n\tLCCSCF_ALLOW_EXPIRED\t\t\t\u003d (1 \u003c\u003c 3),\n\tLCCSCF_ALLOW_INSECURE\t\t\t\u003d (1 \u003c\u003c 4),\n\tLCCSCF_H2_QUIRK_NGHTTP2_END_STREAM\t\u003d (1 \u003c\u003c 5),\n\tLCCSCF_H2_QUIRK_OVERFLOWS_TXCR\t\t\u003d (1 \u003c\u003c 6),\n\tLCCSCF_H2_AUTH_BEARER\t\t\t\u003d (1 \u003c\u003c 7),\n\tLCCSCF_H2_HEXIFY_AUTH_TOKEN\t\t\u003d (1 \u003c\u003c 8),\n\tLCCSCF_H2_MANUAL_RXFLOW\t\t\t\u003d (1 \u003c\u003c 9),\n\tLCCSCF_HTTP_MULTIPART_MIME\t\t\u003d (1 \u003c\u003c 10),\n\tLCCSCF_HTTP_X_WWW_FORM_URLENCODED\t\u003d (1 \u003c\u003c 11),\n\tLCCSCF_HTTP_NO_FOLLOW_REDIRECT\t\t\u003d (1 \u003c\u003c 12),\n\tLCCSCF_HTTP_NO_CACHE_CONTROL\t\t\u003d (1 \u003c\u003c 13),\n\n\tLCCSCF_ALLOW_REUSE_ADDR\t\t\t\t\u003d (1 \u003c\u003c 14),\n\t/**\u003c allow reuse local addresses in a bind call\n\t * When the listening socket is bound to INADDR_ANY with a specific port \n\t * then it is not possible to bind to this port for any local address\n\t */\n\n\tLCCSCF_IPV6_PREFER_PUBLIC_ADDR\t\t\t\t\u003d (1 \u003c\u003c 15),\n\t/**\u003c RFC5014 - For IPv6 systems with SLAAC config, allow for preference\n\t * to bind a socket to public address vs temporary private address\n\t */\n\n\tLCCSCF_PIPELINE\t\t\t\t\u003d (1 \u003c\u003c 16),\n\t\t/**\u003c Serialize / pipeline multiple client connections\n\t\t * on a single connection where possible.\n\t\t *\n\t\t * HTTP/1.0: possible if Keep-Alive: yes sent by server\n\t\t * HTTP/1.1: always possible... uses pipelining\n\t\t * HTTP/2: always possible... uses parallel streams\n\t\t */\n\tLCCSCF_MUXABLE_STREAM\t\t\t\u003d (1 \u003c\u003c 17),\n\tLCCSCF_H2_PRIOR_KNOWLEDGE\t\t\u003d (1 \u003c\u003c 18),\n\tLCCSCF_WAKE_SUSPEND__VALIDITY\t\t\u003d (1 \u003c\u003c 19),\n\t/* our validity checks are important enough to wake from suspend */\n\tLCCSCF_PRIORITIZE_READS\t\t\t\u003d (1 \u003c\u003c 20),\n\t/**\u003c\n\t * Normally lws balances reads and writes on all connections, so both\n\t * are possible even on busy connections, and we go around the event\n\t * loop more often to facilitate that, even if there is pending data.\n\t *\n\t * This flag indicates that you want to handle any pending reads on this\n\t * connection without yielding the service loop for anything else. This\n\t * means you may block other connection processing in favour of incoming\n\t * data processing on this one if it receives back to back incoming rx.\n\t */\n\tLCCSCF_SECSTREAM_CLIENT\t\t\t\u003d (1 \u003c\u003c 21),\n\t/**\u003c used to mark client wsi as bound to secure stream */\n\tLCCSCF_SECSTREAM_PROXY_LINK\t\t\u003d (1 \u003c\u003c 22),\n\t/**\u003c client is a link between SS client and SS proxy */\n\tLCCSCF_SECSTREAM_PROXY_ONWARD\t\t\u003d (1 \u003c\u003c 23),\n\t/**\u003c client the SS proxy's onward connection */\n\n\tLCCSCF_IP_LOW_LATENCY\t\t\t\u003d (1 \u003c\u003c 24),\n\t/**\u003c set the \u0022low delay\u0022 bit on the IP packets of this connection */\n\tLCCSCF_IP_HIGH_THROUGHPUT\t\t\u003d (1 \u003c\u003c 25),\n\t/**\u003c set the \u0022high throughput\u0022 bit on the IP packets of this\n\t * connection */\n\tLCCSCF_IP_HIGH_RELIABILITY\t\t\u003d (1 \u003c\u003c 26),\n\t/**\u003c set the \u0022high reliability\u0022 bit on the IP packets of this\n\t * connection */\n\tLCCSCF_IP_LOW_COST\t\t\t\u003d (1 \u003c\u003c 27),\n\t/**\u003c set the \u0022minimize monetary cost\u0022 bit on the IP packets of this\n\t * connection */\n\tLCCSCF_CONMON\t\t\t\t\u003d (1 \u003c\u003c 28),\n\t/**\u003c If LWS_WITH_CONMON enabled for build, keeps a copy of the\n\t * getaddrinfo results so they can be queried subsequently */\n\tLCCSCF_ACCEPT_TLS_DOWNGRADE_REDIRECTS\t\u003d (1 \u003c\u003c 29),\n\t/**\u003c By default lws rejects https redirecting to http. Set this\n\t * flag on the client connection to allow it. */\n\tLCCSCF_CACHE_COOKIES\t\t\t\u003d (1 \u003c\u003c 30),\n\t/**\u003c If built with -DLWS_WITH_CACHE_NSCOOKIEJAR, store and reapply\n\t * http cookies in a Netscape Cookie Jar on this connection */\n};\n\n/** struct lws_client_connect_info - parameters to connect with when using\n *\t\t\t\t lws_client_connect_via_info() */\n\nstruct lws_client_connect_info {\n\tstruct lws_context *context;\n\t/**\u003c lws context to create connection in */\n\tconst char *address;\n\t/**\u003c remote address to connect to */\n\tint port;\n\t/**\u003c remote port to connect to */\n\tint ssl_connection;\n\t/**\u003c 0, or a combination of LCCSCF_ flags */\n\tconst char *path;\n\t/**\u003c URI path. Prefix with + for a UNIX socket. (+@ for\n * a Linux abstract-namespace socket) */\n\tconst char *host;\n\t/**\u003c content of host header */\n\tconst char *origin;\n\t/**\u003c content of origin header */\n\tconst char *protocol;\n\t/**\u003c list of ws protocols we could accept */\n\tint ietf_version_or_minus_one;\n\t/**\u003c deprecated: currently leave at 0 or -1 */\n\tvoid *userdata;\n\t/**\u003c if non-NULL, use this as wsi user_data instead of malloc it */\n\tconst void *client_exts;\n\t/**\u003c UNUSED... provide in info.extensions at context creation time */\n\tconst char *method;\n\t/**\u003c if non-NULL, do this http method instead of ws[s] upgrade.\n\t * use \u0022GET\u0022 to be a simple http client connection. \u0022RAW\u0022 gets\n\t * you a connected socket that lws itself will leave alone once\n\t * connected. */\n\tstruct lws *parent_wsi;\n\t/**\u003c if another wsi is responsible for this connection, give it here.\n\t * this is used to make sure if the parent closes so do any\n\t * child connections first. */\n\tconst char *uri_replace_from;\n\t/**\u003c if non-NULL, when this string is found in URIs in\n\t * text/html content-encoding, it's replaced with uri_replace_to */\n\tconst char *uri_replace_to;\n\t/**\u003c see uri_replace_from */\n\tstruct lws_vhost *vhost;\n\t/**\u003c vhost to bind to (used to determine related SSL_CTX) */\n\tstruct lws **pwsi;\n\t/**\u003c if not NULL, store the new wsi here early in the connection\n\t * process. Although we return the new wsi, the call to create the\n\t * client connection does progress the connection somewhat and may\n\t * meet an error that will result in the connection being scrubbed and\n\t * NULL returned. While the wsi exists though, he may process a\n\t * callback like CLIENT_CONNECTION_ERROR with his wsi: this gives the\n\t * user callback a way to identify which wsi it is that faced the error\n\t * even before the new wsi is returned and even if ultimately no wsi\n\t * is returned.\n\t */\n\tconst char *iface;\n\t/**\u003c NULL to allow routing on any interface, or interface name or IP\n\t * to bind the socket to */\n\tint local_port;\n\t/**\u003c 0 to pick an ephemeral port, or a specific local port\n\t * to bind the socket to */\n\tconst char *local_protocol_name;\n\t/**\u003c NULL: .protocol is used both to select the local protocol handler\n\t * to bind to and as the list of remote ws protocols we could\n\t * accept.\n\t * non-NULL: this protocol name is used to bind the connection to\n\t * the local protocol handler. .protocol is used for the\n\t * list of remote ws protocols we could accept */\n\tconst char *alpn;\n\t/**\u003c NULL: allow lws default ALPN list, from vhost if present or from\n\t * list of roles built into lws\n\t * non-NULL: require one from provided comma-separated list of alpn\n\t * tokens\n\t */\n\n\tvoid *opaque_user_data;\n\t/**\u003c This data has no meaning to lws but is applied to the client wsi\n\t * and can be retrieved by user code with lws_get_opaque_user_data().\n\t * It's also provided with sequencer messages if the wsi is bound to\n\t * an lws_seq_t.\n\t */\n\n\tconst lws_retry_bo_t *retry_and_idle_policy;\n\t/**\u003c optional retry and idle policy to apply to this connection.\n\t * Currently only the idle parts are applied to the connection.\n\t */\n\n\tint\t\tmanual_initial_tx_credit;\n\t/**\u003c if LCCSCF_H2_MANUAL_REFLOW is set, this becomes the initial tx\n\t * credit for the stream.\n\t */\n\n\tuint8_t\t\tsys_tls_client_cert;\n\t/**\u003c 0 means no client cert. 1+ means apply lws_system client cert 0+\n\t * to the client connection.\n\t */\n\n\tuint8_t\t\tpriority;\n\t/**\u003c 0 means normal priority... otherwise sets the IP priority on\n\t * packets coming from this connection, from 1 - 7. Setting 7\n\t * (network management priority) requires CAP_NET_ADMIN capability but\n\t * the others can be set by anyone.\n\t */\n\n#if defined(LWS_ROLE_MQTT)\n\tconst lws_mqtt_client_connect_param_t *mqtt_cp;\n#else\n\tvoid\t\t*mqtt_cp;\n#endif\n\n#if defined(LWS_WITH_SYS_FAULT_INJECTION)\n\tlws_fi_ctx_t\t\t\t\tfic;\n\t/**\u003c Attach external Fault Injection context to the client wsi,\n\t * hierarchy is wsi -\u003e vhost -\u003e context */\n#endif\n\t/* for convenience, available when FI disabled in build */\n\tconst char\t\t\t\t*fi_wsi_name;\n\t/**\u003c specific Fault Injection namespace name for wsi created for this\n\t * connection, allows targeting by \u0022wsi\u003dXXX/...\u0022 if you give XXX here.\n\t */\n\n\tuint16_t\t\t\t\tkeep_warm_secs;\n\t/**\u003c 0 means 5s. If the client connection to the endpoint becomes idle,\n\t * defer closing it for this many seconds in case another outgoing\n\t * connection to the same endpoint turns up.\n\t */\n\n\tlws_log_cx_t\t\t\t\t*log_cx;\n\t/**\u003c NULL to use lws_context log context, else a pointer to a log\n\t * context template to take a copy of for this wsi. Used to isolate\n\t * wsi-specific logs into their own stream or file.\n\t */\n\tconst char *auth_username;\n\tconst char *auth_password;\n\n#if defined(LWS_ROLE_WS)\n\tuint8_t\t\tallow_reserved_bits;\n\t/**\u003c non-zero to allow reserved bits. You can get it by lws_get_reserved_bits().\n\t * Note: default zero means close the websocket connection for non-zero rsv.\n\t */\n\n\tuint8_t\t\tallow_unknown_opcode;\n\t/**\u003c non-zero to allow unknown opcode. You can get it by `lws_get_opcode`.\n\t * None: default zero means close the websocket connection for unknown opcode.\n\t */\n#endif\n\n\t/* Add new things just above here ---^\n\t * This is part of the ABI, don't needlessly break compatibility\n\t *\n\t * The below is to ensure later library versions with new\n\t * members added above will see 0 (default) even if the app\n\t * was not built against the newer headers.\n\t */\n\n\tvoid *_unused[4]; /**\u003c dummy */\n};\n\n/**\n * lws_client_connect_via_info() - Connect to another websocket server\n * \u005cparam ccinfo: pointer to lws_client_connect_info struct\n *\n *\tThis function creates a connection to a remote server using the\n *\tinformation provided in ccinfo.\n */\nLWS_VISIBLE LWS_EXTERN struct lws *\nlws_client_connect_via_info(const struct lws_client_connect_info *ccinfo);\n\n/**\n * lws_init_vhost_client_ssl() - also enable client SSL on an existing vhost\n *\n * \u005cparam info: client ssl related info\n * \u005cparam vhost: which vhost to initialize client ssl operations on\n *\n * You only need to call this if you plan on using SSL client connections on\n * the vhost. For non-SSL client connections, it's not necessary to call this.\n *\n * The following members of info are used during the call\n *\n *\t - options must have LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT set,\n *\t otherwise the call does nothing\n *\t - provided_client_ssl_ctx must be NULL to get a generated client\n *\t ssl context, otherwise you can pass a prepared one in by setting it\n *\t - ssl_cipher_list may be NULL or set to the client valid cipher list\n *\t - ssl_ca_filepath may be NULL or client cert filepath\n *\t - ssl_cert_filepath may be NULL or client cert filepath\n *\t - ssl_private_key_filepath may be NULL or client cert private key\n *\n * You must create your vhost explicitly if you want to use this, so you have\n * a pointer to the vhost. Create the context first with the option flag\n * LWS_SERVER_OPTION_EXPLICIT_VHOSTS and then call lws_create_vhost() with\n * the same info struct.\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_init_vhost_client_ssl(const struct lws_context_creation_info *info,\n\t\t\t struct lws_vhost *vhost);\n/**\n * lws_http_client_read() - consume waiting received http client data\n *\n * \u005cparam wsi: client connection\n * \u005cparam buf: pointer to buffer pointer - fill with pointer to your buffer\n * \u005cparam len: pointer to chunk length - fill with max length of buffer\n *\n * This is called when the user code is notified client http data has arrived.\n * The user code may choose to delay calling it to consume the data, for example\n * waiting until an onward connection is writeable.\n *\n * For non-chunked connections, up to len bytes of buf are filled with the\n * received content. len is set to the actual amount filled before return.\n *\n * For chunked connections, the linear buffer content contains the chunking\n * headers and it cannot be passed in one lump. Instead, this function will\n * call back LWS_CALLBACK_RECEIVE_CLIENT_HTTP_READ with in pointing to the\n * chunk start and len set to the chunk length. There will be as many calls\n * as there are chunks or partial chunks in the buffer.\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_http_client_read(struct lws *wsi, char **buf, int *len);\n\n/**\n * lws_http_client_http_response() - get last HTTP response code\n *\n * \u005cparam wsi: client connection\n *\n * Returns the last server response code, eg, 200 for client http connections.\n * If there is no valid response, it will return 0.\n *\n * You should capture this during the LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP\n * callback, because after that the memory reserved for storing the related\n * headers is freed and this value is lost.\n */\nLWS_VISIBLE LWS_EXTERN unsigned int\nlws_http_client_http_response(struct lws *wsi);\n\n/**\n * lws_tls_client_vhost_extra_cert_mem() - add more certs to vh client tls ctx\n *\n * \u005cparam vh: the vhost to give more client certs to\n * \u005cparam der: pointer to der format additional cert\n * \u005cparam der_len: size in bytes of der\n *\n * After the vhost is created with one cert for client verification, you\n * can add additional, eg, intermediate, certs to the client tls context\n * of the vhost, for use with validating the incoming server cert(s).\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_tls_client_vhost_extra_cert_mem(struct lws_vhost *vh,\n\t\tconst uint8_t *der, size_t der_len);\n\n/**\n * lws_client_http_body_pending() - control if client connection needs to send body\n *\n * \u005cparam wsi: client connection\n * \u005cparam something_left_to_send: nonzero if need to send more body, 0 (default)\n * \t\t\t\tif nothing more to send\n *\n * If you will send payload data with your HTTP client connection, eg, for POST,\n * when you set the related http headers in\n * LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER callback you should also call\n * this API with something_left_to_send nonzero, and call\n * lws_callback_on_writable(wsi);\n *\n * After sending the headers, lws will call your callback with\n * LWS_CALLBACK_CLIENT_HTTP_WRITEABLE reason when writable. You can send the\n * next part of the http body payload, calling lws_callback_on_writable(wsi);\n * if there is more to come, or lws_client_http_body_pending(wsi, 0); to\n * let lws know the last part is sent and the connection can move on.\n */\nLWS_VISIBLE LWS_EXTERN void\nlws_client_http_body_pending(struct lws *wsi, int something_left_to_send);\n\n/**\n * lws_client_http_multipart() - issue appropriate multipart header or trailer\n *\n * \u005cparam wsi: client connection\n * \u005cparam name: multipart header name field, or NULL if end of multipart\n * \u005cparam filename: multipart header filename field, or NULL if none\n * \u005cparam content_type: multipart header content-type part, or NULL if none\n * \u005cparam p: pointer to position in buffer\n * \u005cparam end: end of buffer\n *\n * This issues a multipart mime boundary, or terminator if name \u003d NULL.\n *\n * Returns 0 if OK or nonzero if couldn't fit in buffer\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_client_http_multipart(struct lws *wsi, const char *name,\n\t\t\t const char *filename, const char *content_type,\n\t\t\t char **p, char *end);\n\n/**\n * lws_http_basic_auth_gen() - helper to encode client basic auth string\n *\n * \u005cparam user: user name\n * \u005cparam pw: password\n * \u005cparam buf: where to store base64 result\n * \u005cparam len: max usable size of buf\n *\n * Encodes a username and password in Basic Auth format for use with the\n * Authorization header. On return, buf is filled with something like\n * \u0022Basic QWxhZGRpbjpPcGVuU2VzYW1l\u0022.\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_http_basic_auth_gen(const char *user, const char *pw, char *buf, size_t len);\n\n/**\n * lws_http_basic_auth_gen2() - helper to encode client basic auth string\n *\n * \u005cparam user: user name\n * \u005cparam pw: password\n * \u005cparam pwd_len: count of bytes in password\n * \u005cparam buf: where to store base64 result\n * \u005cparam len: max usable size of buf\n *\n * Encodes a username and password in Basic Auth format for use with the\n * Authorization header. On return, buf is filled with something like\n * \u0022Basic QWxhZGRpbjpPcGVuU2VzYW1l\u0022.\n *\n * This differs from lws_http_baic_auth_gen() in that NUL bytes can\n * appear in the password due to an explicit password length argument.\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_http_basic_auth_gen2(const char *user, const void *pw, size_t pwd_len,\n char *buf, size_t len);\n\n/**\n * lws_tls_session_is_reused() - returns nonzero if tls session was cached\n *\n * \u005cparam wsi: the wsi\n *\n * Returns zero if the tls session is fresh, else nonzero if the tls session was\n * taken from the cache. If lws is built with LWS_WITH_TLS_SESSIONS and the vhost\n * was created with the option LWS_SERVER_OPTION_ENABLE_TLS_SESSION_CACHE, then\n * on full tls session establishment of a client connection, the session is added\n * to the tls cache.\n *\n * This lets you find out if your session was new (0) or from the cache (nonzero),\n * it'a mainly useful for stats and testing.\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_tls_session_is_reused(struct lws *wsi);\n\n///@}\n","s":{"c":1751770963,"u": 1744}} ],"g": 8826,"chitpc": 0,"ehitpc": 0,"indexed":0 , "ab": 1, "si": 0, "db":0, "di":0, "sat":0, "lfc": "0000"}