michael@0: /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* vim: set sw=2 ts=8 et tw=80 : */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsICancelable.idl"
michael@0: 
michael@0: interface nsIHttpChannel;
michael@0: interface nsIHttpAuthenticableChannel;
michael@0: 
michael@0: /**
michael@0:  * nsIHttpChannelAuthProvider
michael@0:  *
michael@0:  * This interface is intended for providing authentication for http-style
michael@0:  * channels, like nsIHttpChannel and nsIWebSocket, which implement the
michael@0:  * nsIHttpAuthenticableChannel interface.
michael@0:  *
michael@0:  * When requesting pages AddAuthorizationHeaders MUST be called
michael@0:  * in order to get the http cached headers credentials. When the request is
michael@0:  * unsuccessful because of receiving either a 401 or 407 http response code
michael@0:  * ProcessAuthentication MUST be called and the page MUST be requested again
michael@0:  * with the new credentials that the user has provided. After a successful
michael@0:  * request, checkForSuperfluousAuth MAY be called, and disconnect MUST be
michael@0:  * called.
michael@0:  */
michael@0: 
michael@0: [scriptable, uuid(c68f3def-c7c8-4ee8-861c-eef49a48b702)]
michael@0: interface nsIHttpChannelAuthProvider : nsICancelable
michael@0: {
michael@0:   /**
michael@0:    * Initializes the http authentication support for the channel.
michael@0:    * Implementations must hold a weak reference of the channel.
michael@0:    */
michael@0:   void init(in nsIHttpAuthenticableChannel channel);
michael@0: 
michael@0:   /**
michael@0:    * Upon receipt of a server challenge, this function is called to determine
michael@0:    * the credentials to send.
michael@0:    *
michael@0:    * @param httpStatus
michael@0:    *        the http status received.
michael@0:    * @param sslConnectFailed
michael@0:    *        if the last ssl tunnel connection attempt was or not successful.
michael@0:    * @param callback
michael@0:    *        the callback to be called when it returns NS_ERROR_IN_PROGRESS.
michael@0:    *        The implementation must hold a weak reference.
michael@0:    *
michael@0:    * @returns NS_OK if the credentials were got and set successfully.
michael@0:    *          NS_ERROR_IN_PROGRESS if the credentials are going to be asked to
michael@0:    *                               the user. The channel reference must be
michael@0:    *                               alive until the feedback from
michael@0:    *                               nsIHttpAuthenticableChannel's methods or
michael@0:    *                               until disconnect be called.
michael@0:    */
michael@0:   void processAuthentication(in unsigned long httpStatus,
michael@0:                              in boolean sslConnectFailed);
michael@0: 
michael@0:   /**
michael@0:    * Add credentials from the http auth cache.
michael@0:    */
michael@0:   void addAuthorizationHeaders();
michael@0: 
michael@0:   /**
michael@0:    * Check if an unnecessary(and maybe malicious) url authentication has been
michael@0:    * provided.
michael@0:    */
michael@0:   void checkForSuperfluousAuth();
michael@0: 
michael@0:   /**
michael@0:    * Cancel pending user auth prompts and release the callback and channel
michael@0:    * weak references.
michael@0:    */
michael@0:   void disconnect(in nsresult status);
michael@0: };