lws-client.h

Go to the documentation of this file.

/*
 * libwebsockets - small server side websockets and web server implementation
 *
 * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to
 * deal in the Software without restriction, including without limitation the
 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 * IN THE SOFTWARE.
 */


 
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_HTTP_NO_CACHE_CONTROL            = (1 << 13),
 
        LCCSCF_ALLOW_REUSE_ADDR                         = (1 << 14),
 
        LCCSCF_IPV6_PREFER_PUBLIC_ADDR                          = (1 << 15),
 
        LCCSCF_PIPELINE                         = (1 << 16),
        LCCSCF_MUXABLE_STREAM                   = (1 << 17),
        LCCSCF_H2_PRIOR_KNOWLEDGE               = (1 << 18),
        LCCSCF_WAKE_SUSPEND__VALIDITY           = (1 << 19),
        /* our validity checks are important enough to wake from suspend */
        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),
        LCCSCF_ALLOW_EARLY_DATA                 = (int)(1u << 31),
};
 
/*
 * All lws_tls...() functions must return this type, converting the
 * native backend result and doing the extra work to determine which one
 * as needed.
 *
 * Native TLS backend return codes are NOT ALLOWED outside the backend.
 *
 * Non-SSL mode also uses these types.
 */
enum lws_ssl_capable_status {
        LWS_SSL_CAPABLE_ERROR                   = -1, /* it failed */
        LWS_SSL_CAPABLE_DONE                    = 0,  /* it succeeded */
        LWS_SSL_CAPABLE_MORE_SERVICE_READ       = -2, /* retry WANT_READ */
        LWS_SSL_CAPABLE_MORE_SERVICE_WRITE      = -3, /* retry WANT_WRITE */
};

 
struct lws_client_connect_info {
        struct lws_context *context;
        const char *address;
        int port;
        int ssl_connection;
        const char *path;
        const char *host;
        const char *origin;
        const char *protocol;
        int ietf_version_or_minus_one;
        void *userdata;
        const void *client_exts;
        const char *method;
        struct lws *parent_wsi;
        const char *uri_replace_from;
        const char *uri_replace_to;
        struct lws_vhost *vhost;
        struct lws **pwsi;
        const char *iface;
        int local_port;
        const char *local_protocol_name;
        const char *alpn;
 
        void *opaque_user_data;
 
        const lws_retry_bo_t *retry_and_idle_policy;
 
        int             manual_initial_tx_credit;
 
        uint8_t         sys_tls_client_cert;
 
        uint8_t         priority;
 
#if defined(LWS_ROLE_MQTT)
        const lws_mqtt_client_connect_param_t *mqtt_cp;
#else
        void            *mqtt_cp;
#endif
 
#if defined(LWS_WITH_SYS_FAULT_INJECTION)
        lws_fi_ctx_t                            fic;
#endif
        /* for convenience, available when FI disabled in build */
        const char                              *fi_wsi_name;
 
        uint16_t                                keep_warm_secs;
 
        lws_log_cx_t                            *log_cx;
        const char *auth_username;
        const char *auth_password;
 
#if defined(LWS_ROLE_WS)
        uint8_t         allow_reserved_bits;
 
        uint8_t         allow_unknown_opcode;
#endif
 
        /* Add new things just above here ---^
         * This is part of the ABI, don't needlessly break compatibility
         *
         * The below is to ensure later library versions with new
         * members added above will see 0 (default) even if the app
         * was not built against the newer headers.
         */
 
        void *_unused[4]; 
};

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);
 
struct lws_http_mp_sm;
typedef int (*lws_http_mp_sm_cb_t)(struct lws_context *cx, char *ft, size_t ft_len, const char **last);

LWS_VISIBLE LWS_EXTERN struct lws_http_mp_sm *
lws_http_mp_sm_init(struct lws *wsi, lws_http_mp_sm_cb_t cb, uint8_t **p, uint8_t *end);

LWS_VISIBLE LWS_EXTERN void
lws_http_mp_sm_destroy(struct lws_http_mp_sm **pphms);

LWS_VISIBLE LWS_EXTERN int
lws_http_mp_sm_fill(struct lws_http_mp_sm *phms, uint8_t **p, uint8_t *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_http_basic_auth_gen2(const char *user, const void *pw, size_t pwd_len,
                         char *buf, size_t len);

LWS_VISIBLE LWS_EXTERN int
lws_tls_session_is_reused(struct lws *wsi);

LWS_VISIBLE LWS_EXTERN enum lws_ssl_capable_status
lws_tls_client_connect(struct lws *wsi, char *errbuf, size_t len);

LWS_VISIBLE LWS_EXTERN int
lws_tls_client_upgrade(struct lws *wsi, int ssl_flags);