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