netwerk/protocol/http/nsIHttpChannelAuthProvider.idl

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set sw=2 ts=8 et tw=80 : */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsICancelable.idl"
   8
   9 interface nsIHttpChannel;
  10 interface nsIHttpAuthenticableChannel;
  11
  12 /**
  13  * nsIHttpChannelAuthProvider
  14  *
  15  * This interface is intended for providing authentication for http-style
  16  * channels, like nsIHttpChannel and nsIWebSocket, which implement the
  17  * nsIHttpAuthenticableChannel interface.
  18  *
  19  * When requesting pages AddAuthorizationHeaders MUST be called
  20  * in order to get the http cached headers credentials. When the request is
  21  * unsuccessful because of receiving either a 401 or 407 http response code
  22  * ProcessAuthentication MUST be called and the page MUST be requested again
  23  * with the new credentials that the user has provided. After a successful
  24  * request, checkForSuperfluousAuth MAY be called, and disconnect MUST be
  25  * called.
  26  */
  27
  28 [uuid(788f331b-2e1f-436c-b405-4f88a31a105b)]
  29 interface nsIHttpChannelAuthProvider : nsICancelable
  30 {
  31   /**
  32    * Initializes the http authentication support for the channel.
  33    * Implementations must hold a weak reference of the channel.
  34    */
  35   [must_use] void init(in nsIHttpAuthenticableChannel channel);
  36
  37   /**
  38    * Upon receipt of a server challenge, this function is called to determine
  39    * the credentials to send.
  40    *
  41    * @param httpStatus
  42    *        the http status received.
  43    * @param sslConnectFailed
  44    *        if the last ssl tunnel connection attempt was or not successful.
  45    * @param callback
  46    *        the callback to be called when it returns NS_ERROR_IN_PROGRESS.
  47    *        The implementation must hold a weak reference.
  48    *
  49    * @returns NS_OK if the credentials were got and set successfully.
  50    *          NS_ERROR_IN_PROGRESS if the credentials are going to be asked to
  51    *                               the user. The channel reference must be
  52    *                               alive until the feedback from
  53    *                               nsIHttpAuthenticableChannel's methods or
  54    *                               until disconnect be called.
  55    */
  56   [must_use] void processAuthentication(in unsigned long httpStatus,
  57                                         in boolean sslConnectFailed);
  58
  59   /**
  60    * Add credentials from the http auth cache.
  61    *
  62    * @param dontUseCachedWWWCreds
  63    *    When true, the method will not add any Authorization headers from
  64    *    the auth cache.
  65    */
  66   [must_use] void addAuthorizationHeaders(in boolean dontUseCachedWWWCreds);
  67
  68   /**
  69    * Check if an unnecessary(and maybe malicious) url authentication has been
  70    * provided.
  71    */
  72   [must_use] void checkForSuperfluousAuth();
  73
  74   /**
  75    * Cancel pending user auth prompts and release the callback and channel
  76    * weak references.
  77    */
  78   [must_use] void disconnect(in nsresult status);
  79
  80   /**
  81    * Clear the proxy ident to not consider it invalid on re-athentication.
  82    * Called when the channel finds out its transaction has been internally
  83    * restarted.
  84    */
  85   void clearProxyIdent();
  86 };