uriloader/base/nsIWebProgress.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   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 "nsISupports.idl"
   8
   9 interface mozIDOMWindowProxy;
  10 interface nsIEventTarget;
  11 interface nsIRequest;
  12 interface nsIWebProgressListener;
  13 webidl BrowsingContext;
  14
  15 /**
  16  * The nsIWebProgress interface is used to add or remove nsIWebProgressListener
  17  * instances to observe the loading of asynchronous requests (usually in the
  18  * context of a DOM window).
  19  *
  20  * nsIWebProgress instances may be arranged in a parent-child configuration,
  21  * corresponding to the parent-child configuration of their respective DOM
  22  * windows.  However, in some cases a nsIWebProgress instance may not have an
  23  * associated DOM window.  The parent-child relationship of nsIWebProgress
  24  * instances is not made explicit by this interface, but the relationship may
  25  * exist in some implementations.
  26  *
  27  * A nsIWebProgressListener instance receives notifications for the
  28  * nsIWebProgress instance to which it added itself, and it may also receive
  29  * notifications from any nsIWebProgress instances that are children of that
  30  * nsIWebProgress instance.
  31  */
  32 [scriptable, builtinclass, uuid(c4d64640-b332-4db6-a2a5-e08566000dc9)]
  33 interface nsIWebProgress : nsISupports
  34 {
  35   /**
  36    * The following flags may be combined to form the aNotifyMask parameter for
  37    * the addProgressListener method.  They limit the set of events that are
  38    * delivered to an nsIWebProgressListener instance.
  39    */
  40
  41   /**
  42    * These flags indicate the state transistions to observe, corresponding to
  43    * nsIWebProgressListener::onStateChange.
  44    *
  45    * NOTIFY_STATE_REQUEST
  46    *   Only receive the onStateChange event if the aStateFlags parameter
  47    *   includes nsIWebProgressListener::STATE_IS_REQUEST.
  48    *
  49    * NOTIFY_STATE_DOCUMENT
  50    *   Only receive the onStateChange event if the aStateFlags parameter
  51    *   includes nsIWebProgressListener::STATE_IS_DOCUMENT.
  52    *
  53    * NOTIFY_STATE_NETWORK
  54    *   Only receive the onStateChange event if the aStateFlags parameter
  55    *   includes nsIWebProgressListener::STATE_IS_NETWORK.
  56    *
  57    * NOTIFY_STATE_WINDOW
  58    *   Only receive the onStateChange event if the aStateFlags parameter
  59    *   includes nsIWebProgressListener::STATE_IS_WINDOW.
  60    *
  61    * NOTIFY_STATE_ALL
  62    *   Receive all onStateChange events.
  63    */
  64   const unsigned long NOTIFY_STATE_REQUEST  = 0x00000001;
  65   const unsigned long NOTIFY_STATE_DOCUMENT = 0x00000002;
  66   const unsigned long NOTIFY_STATE_NETWORK  = 0x00000004;
  67   const unsigned long NOTIFY_STATE_WINDOW   = 0x00000008;
  68   const unsigned long NOTIFY_STATE_ALL      = 0x0000000f;
  69
  70   /**
  71    * These flags indicate the other events to observe, corresponding to the
  72    * other four methods defined on nsIWebProgressListener.
  73    *
  74    * NOTIFY_PROGRESS
  75    *   Receive onProgressChange events.
  76    *
  77    * NOTIFY_STATUS
  78    *   Receive onStatusChange events.
  79    *
  80    * NOTIFY_SECURITY
  81    *   Receive onSecurityChange events.
  82    *
  83    * NOTIFY_LOCATION
  84    *   Receive onLocationChange events.
  85    *
  86    * NOTIFY_CONTENT_BLOCKING
  87    *   Receive onContentBlockingEvent events.
  88    *
  89    * NOTIFY_REFRESH
  90    *   Receive onRefreshAttempted events.
  91    *   This is defined on nsIWebProgressListener2.
  92    */
  93   const unsigned long NOTIFY_PROGRESS         = 0x00000010;
  94   const unsigned long NOTIFY_STATUS           = 0x00000020;
  95   const unsigned long NOTIFY_SECURITY         = 0x00000040;
  96   const unsigned long NOTIFY_LOCATION         = 0x00000080;
  97   const unsigned long NOTIFY_REFRESH          = 0x00000100;
  98   const unsigned long NOTIFY_CONTENT_BLOCKING = 0x00000200;
  99
 100   /**
 101    * This flag enables all notifications.
 102    */
 103   const unsigned long NOTIFY_ALL              = 0x000003ff;
 104
 105   /**
 106    * Registers a listener to receive web progress events.
 107    *
 108    * @param aListener
 109    *        The listener interface to be called when a progress event occurs.
 110    *        This object must also implement nsISupportsWeakReference.
 111    * @param aNotifyMask
 112    *        The types of notifications to receive.
 113    *
 114    * @throw NS_ERROR_INVALID_ARG
 115    *        Indicates that aListener was either null or that it does not
 116    *        support weak references.
 117    * @throw NS_ERROR_FAILURE
 118    *        Indicates that aListener was already registered.
 119    */
 120   void addProgressListener(in nsIWebProgressListener aListener,
 121                            in unsigned long aNotifyMask);
 122
 123   /**
 124    * Removes a previously registered listener of progress events.
 125    *
 126    * @param aListener
 127    *        The listener interface previously registered with a call to
 128    *        addProgressListener.
 129    *
 130    * @throw NS_ERROR_FAILURE
 131    *        Indicates that aListener was not registered.
 132    */
 133   void removeProgressListener(in nsIWebProgressListener aListener);
 134
 135   /**
 136    * BrowsingContext associated with this nsIWebProgress instance, or `null` if
 137    * there is no BrowsingContext.
 138    */
 139   [binaryname(BrowsingContextXPCOM)]
 140   readonly attribute BrowsingContext browsingContext;
 141
 142   [noscript,notxpcom,nostdcall] BrowsingContext getBrowsingContext();
 143
 144   /**
 145    * The DOM window associated with this nsIWebProgress instance.
 146    *
 147    * @throw NS_ERROR_FAILURE
 148    *        Indicates that there is no associated DOM window.
 149    */
 150   readonly attribute mozIDOMWindowProxy DOMWindow;
 151
 152   /**
 153    * Indicates whether DOMWindow.top == DOMWindow.
 154    */
 155   readonly attribute boolean isTopLevel;
 156
 157   /**
 158    * Indicates whether or not a document is currently being loaded
 159    * in the context of this nsIWebProgress instance.
 160    */
 161   readonly attribute boolean isLoadingDocument;
 162
 163   /**
 164    * Contains a load type as specified by the load* constants in
 165    * nsIDocShell:LoadCommand.
 166    */
 167   readonly attribute unsigned long loadType;
 168
 169   /**
 170    * Main thread event target to which progress updates should be
 171    * dispatched. This typically will be a SchedulerEventTarget
 172    * corresponding to the tab requesting updates.
 173    */
 174   attribute nsIEventTarget target;
 175
 176   /**
 177    * The request for the currently loading document. It is null if
 178    * isLoadingDocument is false.
 179    * Note, the request may not be the actual nsIChannel instance used for
 180    * loading, but a dummy RemoteWebProgressRequest. And since redirects are
 181    * hidden from the child processes, this may not reflect the complete
 182    * redirect state of the load.
 183    */
 184   readonly attribute nsIRequest documentRequest;
 185 };