Document authentication changes

interface/wx/webrequest.h

@@ -131,21 +131,11 @@ public:
         State_Active,
 
         /**
-            The server denied the request because of insufficient
+            The request is currently unauthorized. Calling GetAuthChallenge()
-            user credentials. When credentials are provided with
+            returns a challenge object with further details.
-            SetCredentials() the request will be retried with the supplied
-            user credentials.
         */
         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
+        Returns the current authentication challenge object while the request
-        authentification is requested.
+        is in @c State_Unauthorized.
-
-        @param user
-            User name
-        @param password
-            Password
-        @param target
-            Specify the credentials for the server @c CredentialTarget_Server
-            or the proxy @c CredentialTarget_Proxy.
     */
-    void SetCredentials(const wxString& user, const wxString& password,
+    wxWebAuthChallenge* GetAuthChallenge();
-        CredentialTarget target);
+
 
     /**
         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.