From 1a34f3dab9db06e77034db4303d8997f37e9f550 Mon Sep 17 00:00:00 2001
From: Tobias Taschner <TcT2k@users.noreply.github.com>
Date: Thu, 25 Oct 2018 23:02:23 +0200
Subject: [PATCH] Document authentication changes

---
 interface/wx/webrequest.h | 60 +++++++++++++++++----------------------
 1 file changed, 26 insertions(+), 34 deletions(-)

diff --git a/interface/wx/webrequest.h b/interface/wx/webrequest.h
index 457113e301..8ba0ce6934 100644
--- a/interface/wx/webrequest.h
+++ b/interface/wx/webrequest.h
@@ -131,21 +131,11 @@ public:
         State_Active,
 
         /**
-            The server denied the request because of insufficient
-            user credentials. When credentials are provided with
-            SetCredentials() the request will be retried with the supplied
-            user credentials.
+            The request is currently unauthorized. Calling GetAuthChallenge()
+            returns a challenge object with further details.
         */
         State_Unauthorized,
 
-        /**
-            A proxy denied the request because of insufficient
-            user credentials. When credentials are provided with
-            SetCredentials() the request will be retried with the supplied
-            user credentials.
-        */
-        State_UnauthorizedProxy,
-
         /// The request completed successfully and all data has been received.
         State_Completed,
 
@@ -174,16 +164,6 @@ public:
         Storage_None
     };
 
-    /// Possible credential targets used by SetCredentials().
-    enum CredentialTarget
-    {
-        /// Set credentials to be sent to the server.
-        CredentialTarget_Server,
-
-        /// Set credentials to be sent to a proxy.
-        CredentialTarget_Proxy
-    }
-
     /**
         Sets a request header which will be sent to the server by this request.
 
@@ -247,19 +227,11 @@ public:
         const wxString& contentType, wxFileOffset dataSize = wxInvalidOffset);
 
     /**
-        Sets the credentials to be sent to the server or proxy when
-        authentification is requested.
-
-        @param user
-            User name
-        @param password
-            Password
-        @param target
-            Specify the credentials for the server @c CredentialTarget_Server
-            or the proxy @c CredentialTarget_Proxy.
+        Returns the current authentication challenge object while the request
+        is in @c State_Unauthorized.
     */
-    void SetCredentials(const wxString& user, const wxString& password,
-        CredentialTarget target);
+    wxWebAuthChallenge* GetAuthChallenge();
+
 
     /**
         Instructs the request to ignore server error status codes.
@@ -330,6 +302,26 @@ public:
     State GetState() const { return m_state; }
 };
 
+/**
+    Authentication challenge information available via
+    wxWebRequest::GetAuthChallenge().
+
+    Use SetCredentials() to provide user credentials.
+*/
+class wxWebAuthChallenge
+{
+public:
+    /**
+        Used to provide user credentials to the authentication challenge.
+
+        @param user
+            User name.
+        @param password
+            The users password.
+    */
+    void SetCredentials(const wxString& user, const wxString& password);
+};
+
 /**
     A wxWebResponse allows access to the response sent by the server.