From f1d0a0091182bd1a9ab2c518c44cfea4239acde2 Mon Sep 17 00:00:00 2001
From: Tobias Taschner <TcT2k@users.noreply.github.com>
Date: Fri, 26 Oct 2018 23:04:31 +0200
Subject: [PATCH] Update wxWebRequest documentation

---
 interface/wx/webrequest.h | 124 +++++++++++++++++++++++++-------------
 1 file changed, 83 insertions(+), 41 deletions(-)

diff --git a/interface/wx/webrequest.h b/interface/wx/webrequest.h
index 8ba0ce6934..cefcb69e1f 100644
--- a/interface/wx/webrequest.h
+++ b/interface/wx/webrequest.h
@@ -101,12 +101,6 @@
         The request state changed.
     @event{wxEVT_WEBREQUEST_DATA(id, func)}
         A new block of data has been downloaded.
-    @event{wxEVT_WEBREQUEST_DOWNLOAD_PROGRESS(id, func)}
-        This event periodically reports the download progress while the request
-        is active.
-    @event{wxEVT_WEBREQUEST_UPLOAD_PROGRESS(id, func)}
-        This event periodically reports the upload progress while the request
-        is active.
     @endEventTable
 
     @since 3.1.2
@@ -164,6 +158,43 @@ public:
         Storage_None
     };
 
+    /**
+        Send the request to the server asynchronously.
+
+        Events will be triggered on success or failure.
+
+        @see Cancel()
+    */
+    void Start();
+
+    /**
+        Cancel an active request.
+    */
+    void Cancel();
+
+    /**
+        Returns a response object after a successful request.
+
+        Before sending a request or after a failed request this will return
+        @c NULL.
+    */
+    wxWebResponse* GetResponse();
+
+    /**
+        Returns the current authentication challenge object while the request
+        is in @c State_Unauthorized.
+    */
+    wxWebAuthChallenge* GetAuthChallenge();
+
+    /**
+        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.
 
@@ -226,13 +257,6 @@ public:
     void SetData(wxSharedPtr<wxInputStream> dataStream,
         const wxString& contentType, wxFileOffset dataSize = wxInvalidOffset);
 
-    /**
-        Returns the current authentication challenge object while the request
-        is in @c State_Unauthorized.
-    */
-    wxWebAuthChallenge* GetAuthChallenge();
-
-
     /**
         Instructs the request to ignore server error status codes.
 
@@ -268,38 +292,34 @@ public:
         server.
     */
     void SetStorage(Storage storage);
+    ///@}
 
-    /**
-        Send the request to the server asynchronously.
-
-        Events will be triggered on success or failure.
-
-        @see Cancel()
+    /** @name Progress methods
+        Methods that describe the requests progress
     */
-    void Start();
-
-    /**
-        Cancel an active request.
-    */
-    void Cancel();
-
-    /**
-        Returns a response object after a successful request.
-
-        Before sending a request or after a failed request this will return
-        @c NULL.
-    */
-    wxWebResponse* GetResponse();
-
-    /**
-        Returns the id specified while creating this request.
-    */
-    int GetId() const;
-
+    ///@{
     /**
         Returns the current state of the request.
     */
     State GetState() const { return m_state; }
+
+    /// Returns the number of bytes sent to the server.
+    wxFileOffset GetBytesSent() const;
+
+    /// Returns the number of bytes expected to be send to the server.
+    wxFileOffset GetBytesExpectedToSend() const;
+
+    /// Returns the number of bytes received from the server.
+    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.
+    */
+    wxFileOffset GetBytesExpectedToReceive() const;
+    ///@}
 };
 
 /**
@@ -311,6 +331,20 @@ public:
 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 { return m_source; }
+
     /**
         Used to provide user credentials to the authentication challenge.
 
@@ -350,6 +384,11 @@ public:
     */
     wxString GetHeader(const wxString& name) const;
 
+    /**
+        Returns the MIME type of the response (if available).
+    */
+    wxString GetMimeType() const;
+
     /**
         Returns the status code returned by the server.
     */
@@ -365,6 +404,11 @@ public:
     */
     wxInputStream* GetStream();
 
+    /**
+        Returns a suggested filename for the response data.
+    */
+    wxString GetSuggestedFileName() const;
+
     /**
         Returns all response data as a string.
 
@@ -540,5 +584,3 @@ public:
 
 wxEventType wxEVT_WEBREQUEST_STATE;
 wxEventType wxEVT_WEBREQUEST_DATA;
-wxEventType wxEVT_WEBREQUEST_DOWNLOAD_PROGRESS;
-wxEventType wxEVT_WEBREQUEST_UPLOAD_PROGRESS;