/////////////////////////////////////////////////////////////////////////////
// Name:        webrequest.h
// Created:     2018-10-14
// Copyright:   (c) 2018 wxWidgets development team
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxWebRequest

    This class allows for simple HTTP requests using the operating system's
    components as implementation.

    The latest features of the operating system will be used if available
    (e.g. HTTP/2, TLS 1.3).
    System-wide configuration like proxy and SSL certificates will be used
    when possible.
    When using libcurl backend, environment variables `CURL_CA_BUNDLE`,
    `SSL_CERT_FILE` and `SSL_CERT_DIR` are used to change the trusted
    certificates location if they are defined.

    Instances of wxWebRequest are created by using
    wxWebSession::CreateRequest().

    The requests are handled asynchronously and event handlers are used to
    communicate the request status. See wxWebRequestSync for a class that can
    be used to perform synchronous requests.

    The response data may be stored in memory, to a file or processed directly,
    see SetStorage() for details.

    Example usage in an event handler function of some window (i.e. @c this in
    the example below is a wxWindow pointer):

    @code
        // Create the request object
        wxWebRequest request = wxWebSession::GetDefault().CreateRequest(
            this,
            "https://www.wxwidgets.org/downloads/logos/blocks.png"
        );

        if ( !request.IsOk() ) {
            // This is not expected, but handle the error somehow.
        }

        // Bind state event
        Bind(wxEVT_WEBREQUEST_STATE, [](wxWebRequestEvent& evt) {
            switch (evt.GetState())
            {
                // Request completed
                case wxWebRequest::State_Completed:
                {
                    wxImage logoImage(*evt.GetResponse().GetStream());
                    if (logoImage.IsOk())
                        wxLogInfo("Image successfully downloaded");

                    ... do something with it ...

                    break;
                }
                // Request failed
                case wxWebRequest::State_Failed:
                    wxLogError("Could not load logo: %s", evt.GetErrorDescription());
                    break;
            }

        });

        // Start the request
        request.Start();
    @endcode

    The location of where files are downloaded can also be defined prior to any request
    by passing unique IDs to `wxWebSession::GetDefault().CreateRequest()` and processing
    them in your @c wxEVT_WEBREQUEST_STATE handler. For example, create a map of IDs with
    their respective download paths prior to creating any requests. For each call to
    `wxWebSession::GetDefault().CreateRequest()`, pass in the webpath to download and an ID
    from your map. Then, in your @c wxEVT_WEBREQUEST_STATE handler, get the ID from the
    @c wxWebRequestEvent object and look it up from your ID map. Here, you can access the
    download path that you assigned to this ID and proceed to save the file to that location.

    @section apple_http macOS and iOS App Transport Security

    Starting with macOS 10.11 and iOS 9 an application cannot create insecure
    connections (this includes HTTP and unverified HTTPS). You have to include
    additional fields in your Info.plist to enable such connections.
    For further details see the documentation on NSAppTransportSecurity
    <a target=_new href="https://developer.apple.com/documentation/bundleresources/information_property_list/nsapptransportsecurity">here</a>

    @section descriptions Implementation Descriptions

    The following APIs are used per platform, additional details
    about supported features may be found in their documentation.

    Available features by implementation and minimum version:
    <table>
    <tr><th>Operating System</th><th>API</th><th>HTTPS</th><th>HTTP/2</th></tr>
    <tr>
        <td>Windows</td>
        <td>
            <a target=_new href="https://docs.microsoft.com/en-us/windows/desktop/WinHttp/about-winhttp">WinHTTP</a>
        </td>
        <td>Yes</td>
        <td>Windows 10 1607</td>
    </tr>
    <tr>
        <td>macOS</td>
        <td>
            <a target=_new href="https://developer.apple.com/documentation/foundation/urlsession">NSURLSession</a>
        </td>
        <td>macOS 10.9</td>
        <td>macOS 10.11</td>
    </tr>
    <tr>
        <td>iOS</td>
        <td>
            <a target=_new href="https://developer.apple.com/documentation/foundation/urlsession">NSURLSession</a>
        </td>
        <td>iOS 7.0</td>
        <td>iOS 9.0</td>
    </tr>
    <tr>
        <td>Linux</td>
        <td>
            <a target=_new href="https://curl.haxx.se/libcurl/">libcurl</a>
        </td>
        <td>Yes</td>
        <td>7.47.0</td>
    </tr>
    </table>

    @beginEventEmissionTable{wxWebRequestEvent}
    @event{wxEVT_WEBREQUEST_STATE(id, func)}
        The request state changed.
    @event{wxEVT_WEBREQUEST_DATA(id, func)}
        A new block of data has been downloaded.
    @endEventTable

    @since 3.1.5

    @library{wxnet}
    @category{net}

    @see wxWebResponse, wxWebSession
*/
class wxWebRequest
{
public:
    /**
        Possible request states returned by GetState().
    */
    enum State
    {
        /// The request has just been created and Start() has not been called
        State_Idle,

        /**
            The request is currently unauthorized.

            Calling GetAuthChallenge() returns a challenge object with further
            details and calling SetCredentials() on this object will retry the
            request using these credentials.
        */
        State_Unauthorized,

        /**
            The request is about to start.

            An event notifying about the switch to this state is generated when
            Start() is called (unless an error occurs, in which case the state
            becomes State_Failed instead). Handling this event allows to do
            something right before the asynchronous request actually starts.
         */
        State_Active,

        /**
            The request completed successfully and all data has been received.

            The HTTP status code returned by wxWebResponse::GetStatus() will be
            in 100-399 range, and typically 200.
         */
        State_Completed,

        /**
            The request failed.

            This can happen either because the request couldn't be performed at
            all (e.g. a connection error) or if the server returned an HTTP
            error. In the former case wxWebResponse::GetStatus() returns 0,
            while in the latter it returns a value in 400-599 range.
         */
        State_Failed,

        /// The request has been cancelled before completion by calling Cancel()
        State_Cancelled
    };

    /**
        Possible storage types. Set by SetStorage().
    */
    enum Storage
    {
        /**
            All data is collected in memory until the request is complete.

            It can be later retrieved using wxWebResponse::AsString() or
            wxWebResponse::GetStream().
         */
        Storage_Memory,

        /**
            The data is written to a file on disk as it is received.

            This file can be later read from using wxWebResponse::GetStream()
            or otherwise processed using wxWebRequestEvent::GetDataFile().
         */
        Storage_File,

        /**
            The data is not stored by the request and is only available
            via events.

            Data can be retrieved using wxWebRequestEvent::GetDataBuffer() and
            wxWebRequestEvent::GetDataSize() methods from wxEVT_WEBREQUEST_DATA
            handler.
        */
        Storage_None
    };

    /**
        Special timeout values.

        Can be used as argument when calling wxWebRequest::SetTimeouts().

        @since 3.3.2
    */
    enum Timeout
    {
        /**
            Use the default value for the current timeout and implementation.
        */
        Timeout_Default,

        /**
            Set the timeout to infinite (No timeout).
        */
        Timeout_Infinite
    };

    /**
        Default constructor creates an invalid object.

        Initialize it by assigning wxWebSession::CreateRequest() to it before
        using it.

        @see IsOk()
    */
    wxWebRequest();

    /**
        Check if the object is valid.

        If the object is invalid, it must be assigned a valid request before
        any other methods can be used (with the exception of GetNativeHandle()).
    */
    bool IsOk() const;

    /**
        Return the native handle corresponding to this request object.

        @c wxWebRequestHandle is an opaque type containing a value of the
        following type according to the backend being used:

        - For WinHTTP backend, this is @c HINTERNET request handle.
        - For CURL backend, this is a @c CURL struct pointer.
        - For macOS backend, this is @c NSURLSessionTask object pointer.

        Note that this function returns a valid value only after the request is
        started successfully using Start(). Notably, it is guaranteed to return
        a valid value when handling wxWebRequestEvent corresponding to the
        switch to @c State_Active.

        @see wxWebSession::GetNativeHandle()
     */
    wxWebRequestHandle GetNativeHandle() const;

    /**
        Send the request to the server asynchronously.

        Events will be triggered on success or failure.

        The current state must be @c State_Idle, already started requests can't
        be started again.

        @see Cancel()
    */
    void Start();

    /**
        Cancel an active request.

        Note that cancelling is asynchronous, so the application needs to wait
        until the request state becomes @c State_Cancelled to know when the
        request was really cancelled.

        Request must be active when Cancel() is called, i.e. the current state
        can't be @c State_Idle. However, because it can be difficult to avoid
        doing it in some circumstances, Cancel() may be called multiple times
        and only a single wxWebRequestEvent will be sent even in this case.
    */
    void Cancel();

    /**
        Returns a response object after a successful request.

        Before sending a request or after a failed request this will return
        an invalid response object, i.e. such that wxWebResponse::IsOk()
        returns @c false.
    */
    wxWebResponse GetResponse() const;

    /**
        Returns the current authentication challenge object while the request
        is in @c State_Unauthorized.
    */
    wxWebAuthChallenge GetAuthChallenge() const;

    /**
        Returns the id specified while creating this request.
    */
    int GetId() const;

    /** @name Request options
        Methods that set options before starting the request
    */
    ///@{
    /**
        Sets a request header which will be sent to the server by this request.

        The header will be added if it hasn't been set before or replaced
        otherwise.

        @param name
            Name of the header
        @param value
            String value of the header. An empty string will remove the header.
    */
    void SetHeader(const wxString& name, const wxString& value);

    /**
        Set <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html">common</a>
        or expanded HTTP method.

        The default method is GET unless request data is provided in which
        case POST is the default.

        @param method
            HTTP method name, e.g. "GET".
    */
    void SetMethod(const wxString& method);

    /**
        Set the text to be posted to the server.

        After a successful call to this method, the request will use HTTP @c
        POST instead of the default @c GET when it's executed.

        @param text
            The text data to post.
        @param contentType
            The value of HTTP "Content-Type" header, e.g. "text/html;
            charset=UTF-8".
        @param conv
            Conversion used when sending the text to the server
    */
    void SetData(const wxString& text, const wxString& contentType,
        const wxMBConv& conv = wxConvUTF8);

    /**
        Set the binary data to be posted to the server.

        The next request will be a HTTP @c POST instead of the default HTTP
        @c GET and the given @a dataStream will be posted as the body of
        this request.

        Example of use:
        @code
        std::unique_ptr<wxInputStream> stream(new wxFileInputStream("some_file.dat"));
        if ( !stream->IsOk() ) {
            // Handle error (due to e.g. file not found) here.
            ...
            return;
        }
        request.SetData(stream, "application/octet-stream")
        @endcode

        @param dataStream
            The data in this stream will be posted as the request body. The
            pointer may be @NULL, which will result in sending 0 bytes of data,
            but if not empty, should be valid, i.e. wxInputStream::IsOk() must
            return @true. This object takes ownership of the passed in pointer
            and will delete it, i.e. the pointer must be heap-allocated.
        @param contentType
            The value of HTTP "Content-Type" header, e.g.
            "application/octet-stream".
        @param dataSize
            Amount of data which is sent to the server. If set to
            @c wxInvalidOffset all stream data is sent.

        @return @false if @a dataStream is not-empty but invalid or if @a
            dataSize is not specified and the attempt to determine stream size
            failed; @true in all the other cases.
    */
    bool SetData(std::unique_ptr<wxInputStream> dataStream,
        const wxString& contentType, wxFileOffset dataSize = wxInvalidOffset);

    /// @overload
    bool SetData(wxInputStream* dataStream,
        const wxString& contentType, wxFileOffset dataSize = wxInvalidOffset);

    /**
        Sets how response data will be stored.

        The default storage method @c Storage_Memory collects all response data
        in memory until the request is completed. This is fine for most usage
        scenarios like API calls, loading images, etc. For larger downloads or
        if the response data will be used permanently @c Storage_File instructs
        the request to write the response to a temporary file. This temporary
        file may then be read or moved after the request is complete. The file
        will be downloaded to the system temp directory as returned by
        wxStandardPaths::GetTempDir(). To specify a different directory use
        wxWebSession::SetTempDir().

        Sometimes response data needs to be processed while its downloaded from
        the server. For example if the response is in a format that can be
        parsed piece by piece like XML, JSON or an archive format like ZIP.
        In these cases storing the data in memory or a file before being able
        to process it might not be ideal and @c Storage_None should be set.
        With this storage method the data is only available during the
        @c wxEVT_WEBREQUEST_DATA event calls as soon as it's received from the
        server.
    */
    void SetStorage(Storage storage);

    /**
        Set the timeouts for the connection and data exchange time.

        @param connectionTimeoutMs
            Maximum time in milliseconds allowed for connection to the server.
            For WinHTTP backend, this timeout is used for both the server name
            resolution and the connection establishment. For libcurl backend,
            this timeout is used for the complete connection establishment,
            including name resolution.
        @param dataTimeoutMs
            The exact meaning of this parameter depends on the implementation:
            for WinHTTP backend, it is the maximum time allowed for each read
            or write operation. For libcurl backend it is the total time for
            the entire operation, not counting the connection establishment
            time.

        @note Use wxWebRequest::Timeout_Default to set the timeout to the
            default value (default depends on implementation). Use
            wxWebRequest::Timeout_Infinite to set an infinite timeout.

        @remarks The default timeout values vary depending on implementation:
            - For WinHTTP backend, default connection timeout is infinite while
              data timeout is 30 seconds.
            - For CURL backend, default connection timeout is 5 minutes and
              there is no data timeout.

        @see Timeout

        @note This function is currently not implemented for macOS backend and
            does nothing when it is called when using it.

        @since 3.3.2
    */
    void SetTimeouts(long connectionTimeoutMs, long dataTimeoutMs);

    /**
        Explicitly request using HTTP "Basic" authentication with the provided
        credentials.

        If this function is not called, wxWebRequest initially makes a request
        without using any authentication and then requests credentials from the
        application, using the preferred authentication method among those
        supported by both the client and the server, using wxWebAuthChallenge.
        This is the most flexible approach, but it always requires making an
        extra HTTP request.

        If the application knows that "Basic" authentication should be used, it
        can avoid this extra request by calling this function before calling
        Execute(): this will use the provided credentials for the initial
        request.

        Note that when using a proxy with credentials information, proxy
        credentials will be also included in the initial request if this
        function is called when using libcurl backend.

        @since 3.3.2
     */
    void UseBasicAuth(const wxWebCredentials& cred);

    /**
        Flags for disabling security features.

        @since 3.3.0
     */
    enum
    {
        /**
            Disable SSL certificate verification.

            This can be used to accept self-signed or expired certificates.
         */
        Ignore_Certificate = 1,

        /**
            Disable host name verification.

            This can be used to accept a valid certificate for a different host
            than the one it was issued for.
         */
        Ignore_Host = 2,

        /**
            Disable all security checks for maximum insecurity.
         */
        Ignore_All = Ignore_Certificate | Ignore_Host
    };

    /**
        Make connection insecure by disabling security checks.

        Don't use this function unless absolutely necessary as disabling the
        security checks makes the communication insecure by allowing
        man-in-the-middle attacks.

        By default, all security checks are enabled. Passing 0 as @a flags
        (re-)enables all security checks and makes the connection secure again.

        Please note that under macOS this function always disables all the
        security checks if any of them is disabled, i.e. it is not possible to
        skip just the certificate or just the host name verification.

        @since 3.3.0
     */
    void MakeInsecure(int flags = Ignore_All);

    /**
        Disable SSL certificate verification.

        This can be used to connect to self signed servers or other invalid
        SSL connections. Disabling verification makes the communication
        insecure.

        @see MakeInsecure()
    */
    void DisablePeerVerify(bool disable = true);

    /**
        Return @true if SSL certificate verification has been disabled.

        @see DisablePeerVerify(), GetSecurityFlags()
    */
    bool IsPeerVerifyDisabled() const;
    ///@}

    /** @name Progress methods
        Methods that describe the requests progress
    */
    ///@{
    /**
        Returns the current state of the request.
    */
    State GetState() const;

    /**
        Returns the number of bytes sent to the server.

        This value grows monotonically from 0 to GetBytesExpectedToSend().
     */
    wxFileOffset GetBytesSent() const;

    /**
        Returns the total number of bytes expected to be sent to the server.

        This value stays unchanged throughout the request duration.
     */
    wxFileOffset GetBytesExpectedToSend() const;

    /**
        Returns the number of bytes received from the server.

        This value grows monotonically from 0 to GetBytesExpectedToReceive()
        (unless it is unknown).
     */
    wxFileOffset GetBytesReceived() const;

    /**
        Returns the number of bytes expected to be received from the server.

        This value is based on the @c Content-Length header, if none is found
        it will return -1.

        @see wxWebResponse::GetContentLength()
    */
    wxFileOffset GetBytesExpectedToReceive() const;
    ///@}
};

/**
    @class wxWebRequestSync

    This class allows to perform synchronous HTTP requests using the operating
    components as implementation.

    Please note that this class must not be used from the main thread of GUI
    applications, only use it from worker threads.

    Example of use:
    @code
    auto request = wxWebSessionSync::GetDefault().CreateRequest("https://www.wxwidgets.org");
    auto result = request.Execute();
    if ( !result )
    {
        wxLogError("Request failed: %s", result.error);
    }
    else
    {
        // Do something with the response data, e.g. show it in a text control:
        text->SetValue(request.GetResponse().AsString());
    }
    @endcode

    wxWebAuthChallenge is not used with this class, to access protected
    resources the username and password may be specified in the URL itself or
    UseBasicAuth() must be called prior to Execute().

    @note Any reserved characters (see RFC 3986) in the username or password
        must be percent encoded. wxURI::SetUserAndPassword() can be used to
        ensure that this is done correctly.

    @note macOS backend using NSURLSession doesn't handle encoded characters in
        the password (but does handle them in the username). Use wxWebSession or
        UseBasicAuth() if you need to support them under this platform.

    @see wxWebRequest

    @since 3.3.0
 */
class wxWebRequestSync
{
public:
    /**
        Possible request states returned in the state field of Result.
    */
    enum State
    {
        /// This state is not used with synchronous requests.
        State_Idle,

        /**
            The request is unauthorized.

            Use an URL with the username and password to access this resource.
        */
        State_Unauthorized,

        /// This state is not used with synchronous requests.
        State_Active,

        /**
            The request completed successfully and all data has been received.

            The HTTP status code returned by wxWebResponse::GetStatus() will be
            in 100-399 range, and typically 200.
         */
        State_Completed,

        /**
            The request failed.

            This can happen either because the request couldn't be performed at
            all (e.g. a connection error) or if the server returned an HTTP
            error. In the former case wxWebResponse::GetStatus() returns 0,
            while in the latter it returns a value in 400-599 range.
         */
        State_Failed,

        /// This state is not used with synchronous requests.
        State_Cancelled
    };

    /**
        Result of a synchronous operation.
     */
    struct Result
    {
        /**
            The state of the request.

            This field can only take State_Completed, State_Failed or
            State_Unauthorized values for the synchronous requests.
         */
        State state;

        /**
            The error message in case of a failure.

            This field can also be non-empty for State_Unauthorized state.
         */
        wxString error;

        /**
            Returns true if the request failed.

            Example of use:

            @code
            const auto result = request.Execute();
            if ( !result )
            {
                wxLogError("Request failed: %s", result.error);
                return;
            }
            @endcode

            Note that State_Unauthorized is not considered a failure and needs
            to be checked separately.
         */
        bool operator!() const;
    };

    /**
        Possible storage types. Set by SetStorage().
    */
    enum Storage
    {
        /**
            All data is collected in memory until the request is complete.

            It can be later retrieved using wxWebResponse::AsString() or
            wxWebResponse::GetStream().
         */
        Storage_Memory,

        /**
            The data is written to a file on disk as it is received.

            This file can be later read from using wxWebResponse::GetStream()
            or otherwise processed using wxWebRequestEvent::GetDataFile().
         */
        Storage_File,

        /**
            The data is not stored by the request.

            This storage method is not useful for the synchronous requests as
            data is simply lost when it is used, however it is still supported
            just in case the received data is really not needed.
        */
        Storage_None
    };

    /**
        Default constructor creates an invalid object.

        Initialize it by assigning wxWebSessionSync::CreateRequest() to it
        before using it.

        @see IsOk()
    */
    wxWebRequestSync();

    /**
        Check if the object is valid.

        If the object is invalid, it must be assigned a valid request before
        any other methods can be used (with the exception of GetNativeHandle()).
    */
    bool IsOk() const;

    /**
        Return the native handle corresponding to this request object.

        @c wxWebRequestHandle is an opaque type containing a value of the
        following type according to the backend being used:

        - For WinHTTP backend, this is @c HINTERNET request handle.
        - For CURL backend, this is a @c CURL struct pointer.
        - For macOS backend, this is @c NSURLSessionTask object pointer.

        Note that this function returns a valid value only after the request is
        executed successfully using Execute().

        @see wxWebSession::GetNativeHandle()
     */
    wxWebRequestHandle GetNativeHandle() const;

    /**
        Synchronously execute the request.

        This function blocks for potentially long time and so must not be used
        from the main thread.
     */
    Result Execute() const;

    /**
        Returns a response object after a successful request.

        Before sending a request or after a failed request this will return
        an invalid response object, i.e. such that wxWebResponse::IsOk()
        returns @c false.
    */
    wxWebResponse GetResponse() const;

    /** @name Request options
        Methods that set options before starting the request
    */
    ///@{
    /**
        Sets a request header which will be sent to the server by this request.

        The header will be added if it hasn't been set before or replaced
        otherwise.

        @param name
            Name of the header
        @param value
            String value of the header. An empty string will remove the header.
    */
    void SetHeader(const wxString& name, const wxString& value);

    /**
        Set <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html">common</a>
        or expanded HTTP method.

        The default method is GET unless request data is provided in which
        case POST is the default.

        @param method
            HTTP method name, e.g. "GET".
    */
    void SetMethod(const wxString& method);

    /**
        Set the text to be posted to the server.

        After a successful call to this method, the request will use HTTP @c
        POST instead of the default @c GET when it's executed.

        @param text
            The text data to post.
        @param contentType
            The value of HTTP "Content-Type" header, e.g. "text/html;
            charset=UTF-8".
        @param conv
            Conversion used when sending the text to the server
    */
    void SetData(const wxString& text, const wxString& contentType,
        const wxMBConv& conv = wxConvUTF8);

    /**
        Set the binary data to be posted to the server.

        The next request will be a HTTP @c POST instead of the default HTTP
        @c GET and the given @a dataStream will be posted as the body of
        this request.

        Example of use:
        @code
        std::unique_ptr<wxInputStream> stream(new wxFileInputStream("some_file.dat"));
        if ( !stream->IsOk() ) {
            // Handle error (due to e.g. file not found) here.
            ...
            return;
        }
        request.SetData(stream, "application/octet-stream")
        @endcode

        @param dataStream
            The data in this stream will be posted as the request body. The
            pointer may be @NULL, which will result in sending 0 bytes of data,
            but if not empty, should be valid, i.e. wxInputStream::IsOk() must
            return @true. This object takes ownership of the passed in pointer
            and will delete it, i.e. the pointer must be heap-allocated.
        @param contentType
            The value of HTTP "Content-Type" header, e.g.
            "application/octet-stream".
        @param dataSize
            Amount of data which is sent to the server. If set to
            @c wxInvalidOffset all stream data is sent.

        @return @false if @a dataStream is not-empty but invalid or if @a
            dataSize is not specified and the attempt to determine stream size
            failed; @true in all the other cases.
    */
    bool SetData(std::unique_ptr<wxInputStream> dataStream,
        const wxString& contentType, wxFileOffset dataSize = wxInvalidOffset);

    /// @overload
    bool SetData(wxInputStream* dataStream,
        const wxString& contentType, wxFileOffset dataSize = wxInvalidOffset);

    /**
        Sets how response data will be stored.

        The default storage method @c Storage_Memory collects all response data
        in memory until the request is completed. This is fine for most usage
        scenarios like API calls, loading images, etc. For larger downloads or
        if the response data will be used permanently @c Storage_File instructs
        the request to write the response to a temporary file. This temporary
        file may then be read or moved after the request is complete. The file
        will be downloaded to the system temp directory as returned by
        wxStandardPaths::GetTempDir(). To specify a different directory use
        wxWebSession::SetTempDir().

        Sometimes response data needs to be processed while its downloaded from
        the server. For example if the response is in a format that can be
        parsed piece by piece like XML, JSON or an archive format like ZIP.
        In these cases storing the data in memory or a file before being able
        to process it might not be ideal and @c Storage_None should be set.
        With this storage method the data is only available during the
        @c wxEVT_WEBREQUEST_DATA event calls as soon as it's received from the
        server.
    */
    void SetStorage(Storage storage);

    /**
        Flags for disabling security features.

        @since 3.3.0
     */
    enum
    {
        /**
            Disable SSL certificate verification.

            This can be used to accept self-signed or expired certificates.
         */
        Ignore_Certificate = 1,

        /**
            Disable host name verification.

            This can be used to accept a valid certificate for a different host
            than the one it was issued for.
         */
        Ignore_Host = 2,

        /**
            Disable all security checks for maximum insecurity.
         */
        Ignore_All = Ignore_Certificate | Ignore_Host
    };

    /**
        Set the timeouts for the connection and data exchange time.

        @param connectionTimeoutMs
            Maximum time in milliseconds allowed for connection to the server.
            For WinHTTP backend, this timeout is used for both the server name
            resolution and the connection establishment. For libcurl backend,
            this timeout is used for the complete connection establishment,
            including name resolution.
        @param dataTimeoutMs
            The exact meaning of this parameter depends on the implementation:
            for WinHTTP backend, it is the maximum time allowed for each read
            or write operation. For libcurl backend it is the total time for
            the entire operation, not counting the connection establishment
            time.

        @note Use wxWebRequest::Timeout_Default to set the timeout to the
            default value (default depends on implementation). Use
            wxWebRequest::Timeout_Infinite to set an infinite timeout.

        @remarks The default timeout values vary depending on implementation:
            - For WinHTTP backend, default connection timeout is infinite while
              data timeout is 30 seconds.
            - For CURL backend, default connection timeout is 5 minutes and
              there is no data timeout.

        @see Timeout

        @note This function is currently not implemented for macOS backend and
            does nothing when it is called when using it.

        @since 3.3.2
    */
    void SetTimeouts(long connectionTimeoutMs, long dataTimeoutMs);

    /**
        Explicitly request using HTTP "Basic" authentication with the provided
        credentials.

        If this function is not called, wxWebRequestSync will use the
        credentials from the URL itself to authenticate with the server if
        necessary. This has the advantage of supporting multiple authentication
        methods, but requires an extra HTTP request to be made to discover the
        methods supported by the server.

        If the application knows that "Basic" authentication should be used, it
        can avoid this extra request by calling this function before calling
        Execute(): this will use the provided credentials for the initial
        request.

        Note that when using a proxy with credentials information, proxy
        credentials will be also included in the initial request if this
        function is called when using libcurl backend.

        @since 3.3.2
     */
    void UseBasicAuth(const wxWebCredentials& cred);

    /**
        Make connection insecure by disabling security checks.

        Don't use this function unless absolutely necessary as disabling the
        security checks makes the communication insecure by allowing
        man-in-the-middle attacks.

        By default, all security checks are enabled. Passing 0 as @a flags
        (re-)enables all security checks and makes the connection secure again.

        Please notice that this function currently has no effect under macOS.

        @since 3.3.0
     */
    void MakeInsecure(int flags = Ignore_All);

    /**
        Disable SSL certificate verification.

        This can be used to connect to self signed servers or other invalid
        SSL connections. Disabling verification makes the communication
        insecure.

        Please notice that this function currently has no effect under macOS.

        @see MakeInsecure()
    */
    void DisablePeerVerify(bool disable = true);

    /**
        Return @true if SSL certificate verification has been disabled.

        @see DisablePeerVerify(), GetSecurityFlags()
    */
    bool IsPeerVerifyDisabled() const;
    ///@}

    /**
        Returns the total number of bytes received from the server.

        This value is available after calling Execute().
     */
    wxFileOffset GetBytesReceived() const;
};

/**
    Authentication challenge information available via
    wxWebRequest::GetAuthChallenge().

    Use SetCredentials() to provide user credentials, e.g.
    @code
        if ( request.GetState() == wxWebRequest::State_Unauthorized )
        {
            wxWebCredentials cred("me", wxSecretValue("s3krit"));
            request.GetAuthChallenge().SetCredentials(cred);
        }
    @endcode
*/
class wxWebAuthChallenge
{
public:
    enum Source
    {
        /// The server requested authentication
        Source_Server,

        /// A proxy requested authentication
        Source_Proxy
    };

    /**
        Returns which source requested credentials with this challenge.
    */
    Source GetSource() const;

    /**
        Used to provide user credentials to the authentication challenge.

        @see wxWebCredentials
    */
    void SetCredentials(const wxWebCredentials& cred);
};

/**
    Simple class containing the username and password to use for authenticating.

    @since 3.1.5

    @library{wxnet}
    @category{net}

    @see wxWebAuthChallenge
 */
class wxWebCredentials
{
public:
    /**
        Create the new credentials object.

        Note that the password is a wxSecretValue object, to construct it from
        a string you need to explicitly use wxSecretValue ctor.
     */
    wxWebCredentials(const wxString& user = wxString(),
                     const wxSecretValue& password = wxSecretValue());

    /**
        Return true if user name is set.

        This can be used to distinguish this object from the
        default-constructed one.

        @since 3.3.2
     */
    bool IsOk() const;

    /// Return the user.
    const wxString& GetUser() const;

    /**
        Return the password.

        @see wxSecretString
     */
    const wxSecretValue& GetPassword() const;
};

/**
    A wxWebResponse allows access to the response sent by the server.

    @since 3.1.5

    @library{wxnet}
    @category{net}

    @see wxWebRequest, wxWebRequestSync
*/
class wxWebResponse
{
public:
    /**
        Default constructor creates an invalid object.

        Initialize it by assigning wxWebRequest::GetResponse() or
        wxWebRequestSync::GetResponse() to it before using it.

        @see IsOk()
    */
    wxWebResponse();

    /**
        Check if the object is valid.

        No other methods can be used if this function returns @false.
    */
    bool IsOk() const;

    /**
        Returns the final URL.
        This URL might be different than the request URL when a redirection
        occurred.
    */
    wxString GetURL() const;

    /**
        Returns a header from the response or an empty string if the header
        could not be found.

        @param name Name of the header field
    */
    wxString GetHeader(const wxString& name) const;

    /**
        Returns all values of response headers with the same name or an empty
        vector if the header could not be found at all.

        @param name Name of the header fields

        @since 3.3.0

        @see GetHeader()
    */
    std::vector<wxString> GetAllHeaderValues(const wxString& name) const;

    /**
        Get the length of returned data if available.

        Returns the value specified in the @c Content-Length response header
        or @c -1 if not available.
     */
    wxFileOffset GetContentLength() const;

    /**
        Returns the MIME type of the response (if available).

        This is just the MIME type part (e.g., "text/html") of the value returned
        by GetContentType().
    */
    wxString GetMimeType() const;

    /**
        Returns the content type of the response (if available).

        This is the full value of the @c Content-Type header of the response,
        (e.g., a value such as "text/html; charset=utf-8").

        @since 3.3.0
    */
    wxString GetContentType() const;

    /**
        Returns the status code returned by the server.
    */
    int GetStatus() const;

    /**
        Returns the status text of the response.
    */
    wxString GetStatusText() const;

    /**
        Returns a stream which represents the response data sent by the server.
    */
    wxInputStream* GetStream();

    /**
        Returns a suggested filename for the response data.
    */
    wxString GetSuggestedFileName() const;

    /**
        Returns the full path of the file to which data is being saved.

        This is only valid when storage mode is @c Storage_File.
     */
    wxString GetDataFile() const;

    /**
        Returns all response data as a string.

        This is mostly useful for debugging or diagnostics.
    */
    wxString AsString() const;
};

/**
    @class wxWebProxy

    Object describing the proxy settings to be used by the session.

    An object of this type can be created using one of the factory functions
    documented below and passed to wxWebSession::SetProxy() or
    wxWebSessionSync::SetProxy() to use non-default proxy settings.

    For example:
    @code
    auto& session = wxWebSession::GetDefault();
    if ( !session.SetProxy(wxWebProxy::FromURL("http://proxy.example.com:8080")) )
    {
        // proxy couldn't be set, maybe try with another one?
    }
    @endcode

    @note Support for specifying the proxy is not implemented under iOS due to
        the platform limitations.

    @since 3.3.0

    @library{wxnet}
    @category{net}
 */
class wxWebProxy
{
public:
    /**
        Use the specified proxy for all requests.

        The @a url may contain the schema (supported schemas depend on the
        backend, but "http" and "https" are always supported) and the port
        number, but "http" and backend-dependent port number will be used by
        default if they are not specified.

        It may also contain username and password to be used for authenticating
        with the proxy, except under macOS.

        Backend-specific notes:

        - WinHTTP: only "http" and "https" schemas are supported, the default
          port numbers are 80 and 443, respectively.
        - NSURLSession: Same as for WinHTTP with the added limitation that the
          URL may not contain the username and password nor the path, i.e. it
          is limited to just the host name and port.
        - CURL: all schemas supported by libcurl are supported, which also
          includes "socks4" and "socks5", the default port is 1080.
     */
    static wxWebProxy FromURL(const wxString& url);

    /**
        Disable use of the proxy even if one is configured.

        Try to always use direct connection to the server, even if the system,
        or user account, is configured to use a proxy.
     */
    static wxWebProxy Disable();

    static wxWebProxy Default();
};

/**
    Base class for logging debug information from web requests.

    An object of a class derived from this one may be associated with a
    wxWebSession or wxWebSessionSync using wxWebSession::SetDebugLogger() in
    order to receive detailed information about the data exchanged with the
    HTTP server.

    Once this object is associated with a session, its member functions will be
    called to report various events happening during the request processing.

    libcurl-based backend provides the most full-featured logging, with WinHTTP
    backend providing only limited information and NSURLSession-based backend
    currently not providing any logging at all.

    @since 3.3.2

    @library{wxnet}
    @category{net}
*/
class wxWebRequestDebugLogger
{
public:
    /// Default constructor.
    wxWebRequestDebugLogger() = default;

    /**
        Called to notify about an informational message.

        For example, the libcurl-based backend provides details about the
        protocol used (including TLS version when applicable) and the
        connection state using this function.

        @param info A single line informational message.
     */
    virtual void OnInfo(const wxString& info) = 0;

    /**
        Called with the request line sent to the server.

        A typical example of such a line would be `GET /index.html HTTP/1.1`.
     */
    virtual void OnRequestSent(const wxString& line) = 0;

    /**
        Called with the status line received from the server.

        A typical example of such a line would be `HTTP/1.1 200 OK`.
     */
    virtual void OnResponseReceived(const wxString& line) = 0;

    /**
        Called for each header sent to the server.

        This is currently only called when libcurl-based backend is used.

        @param name Name of the header
        @param value String value of the header
     */
    virtual void OnHeaderSent(const wxString& name, const wxString& value) = 0;

    /**
        Called for each header received from the server.

        @param name Name of the header
        @param value String value of the header
     */
    virtual void OnHeaderReceived(const wxString& name, const wxString& value) = 0;

    /**
        Called when other data is sent to the server.

        This data may be binary and encrypted when using HTTPS, so it is
        typically not human-readable, although it may be in some cases (e.g.
        when using a text body with HTTP POST).

        This is currently only called when libcurl-based backend is used or
        when WinHTTP backend is used with synchronous requests.

        @param data Pointer to the received data buffer.
        @param size Size of the received data buffer in bytes.
     */
    virtual void OnDataSent(const void* data, size_t size) = 0;

    /**
        Called when other data is received from the server.

        This data may be binary and encrypted when using HTTPS, so it is
        typically not human-readable, although it may be in some cases (e.g.
        when receiving a text response body).

        @param data Pointer to the received data buffer.
        @param size Size of the received data buffer in bytes.
     */
    virtual void OnDataReceived(const void* data, size_t size) = 0;
};

/**
    @class wxWebSession

    Session allows creating wxWebRequest objects used for the actual HTTP
    requests.

    It also handles session-wide parameters and data used by wxWebRequest
    instances.

    Usually the default session available via wxWebSession::GetDefault()
    should be used. Additional instances might be useful if session separation
    is required. Instances <b>must not</b> be deleted before every active web
    request has finished.

    Every wxWebRequest sharing the same session object will use the same
    cookies. Additionally, an underlying network connection might be kept
    alive to achieve faster additional responses.

    @since 3.1.5

    @library{wxnet}
    @category{net}

    @see wxWebRequest, wxWebSessionSync
*/
class wxWebSession
{
public:
    /**
        Create a new request for the specified URL.

        The specified objects will be notified via wxWebRequestEvent objects
        when the request state changes, e.g. when it is completed. It must be
        specified and its lifetime must be long enough to last until the
        request is completed. In particular, if the handler is a top-level
        window, the request must be cancelled before the window can be closed
        and destroyed.

        If SetBaseURL() had been called before this function, the @a url can be
        relative, e.g. with @c https://foo.com/api as the base URL, passing the
        following values would result in using these full URLs:

        - @c get would become @c https://foo.com/api/get
        - @c /root would become @c https://foo.com/root
        - @c https://bar.org/ would remain unchanged

        @param handler
            The handler object to notify, must be non-null.
        @param url
            The URL of the HTTP resource for this request
        @param id
            Optional id sent with events
        @return
            The new request object, use wxWebRequest::IsOk() to check if its
            creation has succeeded.
    */
    wxWebRequest
    CreateRequest(wxEvtHandler* handler, const wxString& url, int id = wxID_ANY);

    /**
        Retrieve the version information about the implementation library used
        by this session.
    */
    virtual wxVersionInfo GetLibraryVersionInfo() const;

    /**
        Sets a request header in every wxWebRequest created from this session
        after is has been set.

        A good example for a session-wide request header is the @c User-Agent
        header.

        Calling this function with the same header name again replaces the
        previously used value.

        @param name Name of the header
        @param value String value of the header
    */
    void AddCommonHeader(const wxString& name, const wxString& value);

    /**
        Sets the base URL for all requests using non-absolute URLs.

        If this function is called and returns @true, the @a url will be used
        as the base for all the requests created by the subsequent calls to
        CreateRequest() with relative URLs. This is especially useful when
        using some web API which typically uses a common root URL for all its
        endpoints.

        @param url An absolute URL, i.e. including the scheme and the host.
        @return @true if the base URL was set successfully, @false otherwise
            (this happens if the URL couldn't be parsed successfully or was not
            an absolute one).

        @since 3.3.0
     */
    bool SetBaseURL(const wxString& url);

    /**
        Override the default temporary directory that may be used by the
        session implementation, when required.
    */
    void SetTempDir(const wxString& dir);

    /**
        Returns the current temporary directory.

        @see SetTempDir()
    */
    wxString GetTempDir() const;

    /**
        Set the proxy to use for all requests initiated by this session.

        By default, the system default proxy settings are used but this
        function can be called _before_ creating the first request to override
        them.

        @return @true if the proxy was set successfully, @false otherwise (this
            may indicate unsupported URL schema or that the function was called
            after creating the first request).

        @since 3.3.0
     */
    bool SetProxy(const wxWebProxy& proxy);

    /**
        Returns the default session
    */
    static wxWebSession& GetDefault();

    /**
        Creates a new wxWebSession object.

        @a backend may be specified explicitly by using of the predefined @c
        wxWebSessionBackendWinHTTP, @c wxWebSessionBackendURLSession or @c
        wxWebSessionBackendCURL constants to select the corresponding backend
        or left empty to select the default backend. The default depends on
        the current platform: WinHTTP-based implementation is used under MSW,
        NSURLSession-based one under macOS and libcurl-based otherwise.

        Further, if @c WXWEBREQUEST_BACKEND environment variable is defined, it
        overrides the default backend selection, allowing to force the use of
        libcurl-based implementation by default under MSW or macOS platforms,
        for example.

        Use IsOpened() to check if the session creation succeeded.

        @param backend
            The backend web session implementation to use or empty to use the
            default implementation as described above.

        @return
            The created wxWebSession
    */
    static wxWebSession New(const wxString& backend = wxString());

    /**
        Allows to check if the specified backend is available at runtime.

        Usually the default backend should always be available, but e.g. macOS
        before 10.9 does not have the @c NSURLSession implementation available.
    */
    static bool IsBackendAvailable(const wxString& backend);

    /**
        Return the native handle corresponding to this session object.

        @c wxWebSessionHandle is an opaque type containing a value of the
        following type according to the backend being used:

        - For WinHTTP backend, this is @c HINTERNET session handle.
        - For CURL backend, this is a @c CURLM struct pointer.
        - For macOS backend, this is @c NSURLSession object pointer.

        @see wxWebRequest::GetNativeHandle()
     */
    wxWebSessionHandle GetNativeHandle() const;

    /**
        Return @true if the session was successfully opened and can be used.
    */
    bool IsOpened() const;

    /**
        Close the session.

        This frees any resources associated with the session and puts it in an
        invalid state. Another session object can be assigned to it later to
        allow using this object again.

        Note that this is usually unnecessary to call this function explicitly,
        it will be done by the destructor of the object when it is destroyed in
        any case. Also note that the session object resources will remain
        allocated as long as there are any wxWebRequest objects using it still
        in existence.
     */
    void Close();

    /**
        Allows to enable persistent storage for the session.

        Persistent storage is disabled by default, but this function can be
        called to enable it before the first request is created. Note that it
        can't be called any more after creating the first request in this
        session.

        When persistent storage is enabled, the session will store cookies and
        other data between sessions.

        @return @true if the backend supports to modify this setting. @false if
            the setting is not supported by the backend.

        @note This is only implemented in the macOS backend.

        @since 3.3.0
     */
    bool EnablePersistentStorage(bool enable);

    /**
        Enable debug logging for all requests created by this session.

        If @a logger is non-null, it will be used to log detailed debug
        information about the data exchanged with the HTTP server for all
        requests created by this session after this function is called.

        @note Calling this function destroys any previously set logger, make
            sure there are no active requests using it any more before doing
            so to avoid crashes.

        @since 3.3.2
     */
    void SetDebugLogger(std::unique_ptr<wxWebRequestDebugLogger> logger);
};

/**
    @class wxWebSessionSync

    Session allows creating wxWebRequestSync objects used for the synchronous
    HTTP requests.

    This class is similar to wxWebSession but is used for synchronous requests
    only. Please see wxWebSession description for more details.

    @since 3.3.0

    @library{wxnet}
    @category{net}

    @see wxWebRequestSync
*/
class wxWebSessionSync
{
public:
    /**
        Create a new synchronous request for the specified URL.

        If SetBaseURL() had been called before this function, the @a url can be
        relative, e.g. with @c https://foo.com/api as the base URL, passing the
        following values would result in using these full URLs:

        - @c get would become @c https://foo.com/api/get
        - @c /root would become @c https://foo.com/root
        - @c https://bar.org/ would remain unchanged

        @param url
            The URL of the HTTP resource for this request
        @return
            The new request object, use wxWebRequestSync::IsOk() to check if
            its creation has succeeded.
    */
    wxWebRequestSync CreateRequest(const wxString& url);

    /**
        Retrieve the version information about the implementation library used
        by this session.
    */
    virtual wxVersionInfo GetLibraryVersionInfo() const;

    /**
        Sets a request header in every wxWebRequestSync created from this
        session after is has been set.

        A good example for a session-wide request header is the @c User-Agent
        header.

        Calling this function with the same header name again replaces the
        previously used value.

        @param name Name of the header
        @param value String value of the header
    */
    void AddCommonHeader(const wxString& name, const wxString& value);

    /**
        Sets the base URL for all requests using non-absolute URLs.

        If this function is called and returns @true, the @a url will be used
        as the base for all the requests created by the subsequent calls to
        CreateRequest() with relative URLs. This is especially useful when
        using some web API which typically uses a common root URL for all its
        endpoints.

        @param url An absolute URL, i.e. including the scheme and the host.
        @return @true if the base URL was set successfully, @false otherwise
            (this happens if the URL couldn't be parsed successfully or was not
            an absolute one).
     */
    bool SetBaseURL(const wxString& url);

    /**
        Override the default temporary directory that may be used by the
        session implementation, when required.
    */
    void SetTempDir(const wxString& dir);

    /**
        Returns the current temporary directory.

        @see SetTempDir()
    */
    wxString GetTempDir() const;

    /**
        Set the proxy to use for all requests initiated by this session.

        By default, the system default proxy settings are used but this
        function can be called _before_ creating the first request to override
        them.

        @since 3.3.0
     */
    void SetProxy(const wxWebProxy& proxy);

    /**
        Returns the default session
    */
    static wxWebSessionSync& GetDefault();

    /**
        Creates a new wxWebSessionSync object.

        @a backend may be specified explicitly by using of the predefined @c
        wxWebSessionBackendWinHTTP, @c wxWebSessionBackendURLSession or @c
        wxWebSessionBackendCURL constants to select the corresponding backend
        or left empty to select the default backend. The default depends on
        the current platform: WinHTTP-based implementation is used under MSW,
        NSURLSession-based one under macOS and libcurl-based otherwise.

        Further, if @c WXWEBREQUEST_BACKEND environment variable is defined, it
        overrides the default backend selection, allowing to force the use of
        libcurl-based implementation by default under MSW or macOS platforms,
        for example.

        Use IsOpened() to check if the session creation succeeded.

        @param backend
            The backend web session implementation to use or empty to use the
            default implementation as described above.

        @return
            The created wxWebSessionSync
    */
    static wxWebSessionSync New(const wxString& backend = wxString());

    /**
        Allows to check if the specified backend is available at runtime.

        Usually the default backend should always be available, but e.g. macOS
        before 10.9 does not have the @c NSURLSession implementation available.
    */
    static bool IsBackendAvailable(const wxString& backend);

    /**
        Return the native handle corresponding to this session object.

        @c wxWebSessionHandle is an opaque type containing a value of the
        following type according to the backend being used:

        - For WinHTTP backend, this is @c HINTERNET session handle.
        - For CURL backend, this is a @c CURLM struct pointer.
        - For macOS backend, this is @c NSURLSession object pointer.

        @see wxWebRequest::GetNativeHandle()
     */
    wxWebSessionHandle GetNativeHandle() const;

    /**
        Return @true if the session was successfully opened and can be used.
    */
    bool IsOpened() const;

    /**
        Close the session.

        This frees any resources associated with the session and puts it in an
        invalid state. Another session object can be assigned to it later to
        allow using this object again.

        Note that this is usually unnecessary to call this function explicitly,
        it will be done by the destructor of the object when it is destroyed in
        any case. Also note that the session object resources will remain
        allocated as long as there are any wxWebRequest objects using it still
        in existence.
     */
    void Close();

    /**
        Allows to enable persistent storage for the session.

        Persistent storage is disabled by default, but this function can be
        called to enable it before the first request is created. Note that it
        can't be called any more after creating the first request in this
        session.

        When persistent storage is enabled, the session will store cookies and
        other data between sessions.

        @return @true if the backend supports to modify this setting. @false if
            the setting is not supported by the backend.

        @note This is only implemented in the macOS backend.
     */
    bool EnablePersistentStorage(bool enable);

    /**
        Enable debug logging for all requests created by this session.

        If @a logger is non-null, it will be used to log detailed debug
        information about the data exchanged with the HTTP server for all
        requests created by this session after this function is called.

        @note Calling this function destroys any previously set logger, make
            sure there are no active requests using it any more before doing
            so to avoid crashes.

        @since 3.3.2
     */
    void SetDebugLogger(std::unique_ptr<wxWebRequestDebugLogger> logger);
};


/**
    @class wxWebRequestEvent

    A web request event sent during or after server communication.

    @since 3.1.5

    @library{wxnet}
    @category{net,events}

    @see wxWebRequest
*/
class wxWebRequestEvent : public wxEvent
{
public:
    /**
        Return the current state of the request
    */
    wxWebRequest::State GetState() const;

    /**
        Returns a reference to the @c wxWebRequest object which initiated this event.

        @since 3.1.6
    */
    const wxWebRequest& GetRequest() const;

    /**
        The response with the state set to @c State_Complete or empty response
        object for other events.
    */
    const wxWebResponse& GetResponse() const;

    /**
        A textual error description for a client side error
        in case of @c State_Failed
    */
    const wxString& GetErrorDescription() const;

    /**
        Returns the full path of a temporary file containing the response data
        when the state is @c State_Completed and storage is @c Storage_File.

        The file will be removed after the event handlers are called. You can
        move the file to a location of your choice if you want to process the
        contents outside the event handler.
    */
    const wxString& GetDataFile() const;

    /**
        Only for @c wxEVT_WEBREQUEST_DATA events. The buffer is only valid
        inside the event handler.
    */
    ///@{
    const void* GetDataBuffer() const;

    size_t GetDataSize() const;
    ///@}
};

wxEventType wxEVT_WEBREQUEST_STATE;
wxEventType wxEVT_WEBREQUEST_DATA;
