uriloader/base/nsIWebProgress.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is the Mozilla browser.
  17  *
  18  * The Initial Developer of the Original Code is
  19  * Netscape Communications, Inc.
  20  * Portions created by the Initial Developer are Copyright (C) 1999
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Travis Bogard <travis@netscape.com>
  25  *   Darin Fisher <darin@meer.net>
  26  *   Mark Pilgrim <pilgrim@gmail.com>
  27  *
  28  * Alternatively, the contents of this file may be used under the terms of
  29  * either of the GNU General Public License Version 2 or later (the "GPL"),
  30  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  31  * in which case the provisions of the GPL or the LGPL are applicable instead
  32  * of those above. If you wish to allow use of your version of this file only
  33  * under the terms of either the GPL or the LGPL, and not to allow others to
  34  * use your version of this file under the terms of the MPL, indicate your
  35  * decision by deleting the provisions above and replace them with the notice
  36  * and other provisions required by the GPL or the LGPL. If you do not delete
  37  * the provisions above, a recipient may use your version of this file under
  38  * the terms of any one of the MPL, the GPL or the LGPL.
  39  *
  40  * ***** END LICENSE BLOCK ***** */
  41
  42 #include "nsISupports.idl"
  43
  44 interface nsIDOMWindow;
  45 interface nsIWebProgressListener;
  46
  47 /**
  48  * The nsIWebProgress interface is used to add or remove nsIWebProgressListener
  49  * instances to observe the loading of asynchronous requests (usually in the
  50  * context of a DOM window).
  51  *
  52  * nsIWebProgress instances may be arranged in a parent-child configuration,
  53  * corresponding to the parent-child configuration of their respective DOM
  54  * windows.  However, in some cases a nsIWebProgress instance may not have an
  55  * associated DOM window.  The parent-child relationship of nsIWebProgress
  56  * instances is not made explicit by this interface, but the relationship may
  57  * exist in some implementations.
  58  *
  59  * A nsIWebProgressListener instance receives notifications for the
  60  * nsIWebProgress instance to which it added itself, and it may also receive
  61  * notifications from any nsIWebProgress instances that are children of that
  62  * nsIWebProgress instance.
  63  */
  64 [scriptable, uuid(570F39D0-EFD0-11d3-B093-00A024FFC08C)]
  65 interface nsIWebProgress : nsISupports
  66 {
  67   /**
  68    * The following flags may be combined to form the aNotifyMask parameter for
  69    * the addProgressListener method.  They limit the set of events that are
  70    * delivered to an nsIWebProgressListener instance.
  71    */
  72
  73   /**
  74    * These flags indicate the state transistions to observe, corresponding to
  75    * nsIWebProgressListener::onStateChange.
  76    *
  77    * NOTIFY_STATE_REQUEST
  78    *   Only receive the onStateChange event if the aStateFlags parameter
  79    *   includes nsIWebProgressListener::STATE_IS_REQUEST.
  80    *
  81    * NOTIFY_STATE_DOCUMENT
  82    *   Only receive the onStateChange event if the aStateFlags parameter
  83    *   includes nsIWebProgressListener::STATE_IS_DOCUMENT.
  84    *
  85    * NOTIFY_STATE_NETWORK
  86    *   Only receive the onStateChange event if the aStateFlags parameter
  87    *   includes nsIWebProgressListener::STATE_IS_NETWORK.
  88    *
  89    * NOTIFY_STATE_WINDOW
  90    *   Only receive the onStateChange event if the aStateFlags parameter
  91    *   includes nsIWebProgressListener::STATE_IS_WINDOW.
  92    *
  93    * NOTIFY_STATE_ALL
  94    *   Receive all onStateChange events.
  95    */
  96   const unsigned long NOTIFY_STATE_REQUEST  = 0x00000001;
  97   const unsigned long NOTIFY_STATE_DOCUMENT = 0x00000002;
  98   const unsigned long NOTIFY_STATE_NETWORK  = 0x00000004;
  99   const unsigned long NOTIFY_STATE_WINDOW   = 0x00000008;
 100   const unsigned long NOTIFY_STATE_ALL      = 0x0000000f;
 101
 102   /**
 103    * These flags indicate the other events to observe, corresponding to the
 104    * other four methods defined on nsIWebProgressListener.
 105    *
 106    * NOTIFY_PROGRESS
 107    *   Receive onProgressChange events.
 108    *
 109    * NOTIFY_STATUS
 110    *   Receive onStatusChange events.
 111    *
 112    * NOTIFY_SECURITY
 113    *   Receive onSecurityChange events.
 114    *
 115    * NOTIFY_LOCATION
 116    *   Receive onLocationChange events.
 117    *
 118    * NOTIFY_REFRESH
 119    *   Receive onRefreshAttempted events.
 120    *   This is defined on nsIWebProgressListener2.
 121    */
 122   const unsigned long NOTIFY_PROGRESS       = 0x00000010;
 123   const unsigned long NOTIFY_STATUS         = 0x00000020;
 124   const unsigned long NOTIFY_SECURITY       = 0x00000040;
 125   const unsigned long NOTIFY_LOCATION       = 0x00000080;
 126   const unsigned long NOTIFY_REFRESH        = 0x00000100;
 127
 128   /**
 129    * This flag enables all notifications.
 130    */
 131   const unsigned long NOTIFY_ALL            = 0x000001ff;
 132
 133   /**
 134    * Registers a listener to receive web progress events.
 135    *
 136    * @param aListener
 137    *        The listener interface to be called when a progress event occurs.
 138    *        This object must also implement nsISupportsWeakReference.
 139    * @param aNotifyMask
 140    *        The types of notifications to receive.
 141    *
 142    * @throw NS_ERROR_INVALID_ARG
 143    *        Indicates that aListener was either null or that it does not
 144    *        support weak references.
 145    * @throw NS_ERROR_FAILURE
 146    *        Indicates that aListener was already registered.
 147    */
 148   void addProgressListener(in nsIWebProgressListener aListener,
 149                            in unsigned long aNotifyMask);
 150
 151   /**
 152    * Removes a previously registered listener of progress events.
 153    *
 154    * @param aListener
 155    *        The listener interface previously registered with a call to
 156    *        addProgressListener.
 157    *
 158    * @throw NS_ERROR_FAILURE
 159    *        Indicates that aListener was not registered.
 160    */
 161   void removeProgressListener(in nsIWebProgressListener aListener);
 162
 163   /**
 164    * The DOM window associated with this nsIWebProgress instance.
 165    *
 166    * @throw NS_ERROR_FAILURE
 167    *        Indicates that there is no associated DOM window.
 168    */
 169   readonly attribute nsIDOMWindow DOMWindow;
 170
 171   /**
 172    * Indicates whether or not a document is currently being loaded
 173    * in the context of this nsIWebProgress instance.
 174    */
 175   readonly attribute PRBool isLoadingDocument;
 176 };