/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at
http://mozilla.org/MPL/2.0/. */
#include "nsISupports.idl"
interface mozIDOMWindowProxy;
interface nsIEventTarget;
interface nsIRequest;
interface nsIWebProgressListener;
webidl BrowsingContext;
/**
* The nsIWebProgress interface is used to add or remove nsIWebProgressListener
* instances to observe the loading of asynchronous requests (usually in the
* context of a DOM window).
*
* nsIWebProgress instances may be arranged in a parent-child configuration,
* corresponding to the parent-child configuration of their respective DOM
* windows. However, in some cases a nsIWebProgress instance may not have an
* associated DOM window. The parent-child relationship of nsIWebProgress
* instances is not made explicit by this interface, but the relationship may
* exist in some implementations.
*
* A nsIWebProgressListener instance receives notifications for the
* nsIWebProgress instance to which it added itself, and it may also receive
* notifications from any nsIWebProgress instances that are children of that
* nsIWebProgress instance.
*/
[scriptable, builtinclass, uuid(c4d64640-b332-4db6-a2a5-e08566000dc9)]
interface nsIWebProgress : nsISupports
{
/**
* The following flags may be combined to form the aNotifyMask parameter for
* the addProgressListener method. They limit the set of events that are
* delivered to an nsIWebProgressListener instance.
*/
/**
* These flags indicate the state transistions to observe, corresponding to
* nsIWebProgressListener::onStateChange.
*
* NOTIFY_STATE_REQUEST
* Only receive the onStateChange event if the aStateFlags parameter
* includes nsIWebProgressListener::STATE_IS_REQUEST.
*
* NOTIFY_STATE_DOCUMENT
* Only receive the onStateChange event if the aStateFlags parameter
* includes nsIWebProgressListener::STATE_IS_DOCUMENT.
*
* NOTIFY_STATE_NETWORK
* Only receive the onStateChange event if the aStateFlags parameter
* includes nsIWebProgressListener::STATE_IS_NETWORK.
*
* NOTIFY_STATE_WINDOW
* Only receive the onStateChange event if the aStateFlags parameter
* includes nsIWebProgressListener::STATE_IS_WINDOW.
*
* NOTIFY_STATE_ALL
* Receive all onStateChange events.
*/
const unsigned long NOTIFY_STATE_REQUEST = 0x00000001;
const unsigned long NOTIFY_STATE_DOCUMENT = 0x00000002;
const unsigned long NOTIFY_STATE_NETWORK = 0x00000004;
const unsigned long NOTIFY_STATE_WINDOW = 0x00000008;
const unsigned long NOTIFY_STATE_ALL = 0x0000000f;
/**
* These flags indicate the other events to observe, corresponding to the
* other four methods defined on nsIWebProgressListener.
*
* NOTIFY_PROGRESS
* Receive onProgressChange events.
*
* NOTIFY_STATUS
* Receive onStatusChange events.
*
* NOTIFY_SECURITY
* Receive onSecurityChange events.
*
* NOTIFY_LOCATION
* Receive onLocationChange events.
*
* NOTIFY_CONTENT_BLOCKING
* Receive onContentBlockingEvent events.
*
* NOTIFY_REFRESH
* Receive onRefreshAttempted events.
* This is defined on nsIWebProgressListener2.
*/
const unsigned long NOTIFY_PROGRESS = 0x00000010;
const unsigned long NOTIFY_STATUS = 0x00000020;
const unsigned long NOTIFY_SECURITY = 0x00000040;
const unsigned long NOTIFY_LOCATION = 0x00000080;
const unsigned long NOTIFY_REFRESH = 0x00000100;
const unsigned long NOTIFY_CONTENT_BLOCKING = 0x00000200;
/**
* This flag enables all notifications.
*/
const unsigned long NOTIFY_ALL = 0x000003ff;
/**
* Registers a listener to receive web progress events.
*
* @param aListener
* The listener interface to be called when a progress event occurs.
* This object must also implement nsISupportsWeakReference.
* @param aNotifyMask
* The types of notifications to receive.
*
* @throw NS_ERROR_INVALID_ARG
* Indicates that aListener was either null or that it does not
* support weak references.
* @throw NS_ERROR_FAILURE
* Indicates that aListener was already registered.
*/
void addProgressListener(in nsIWebProgressListener aListener,
in unsigned long aNotifyMask);
/**
* Removes a previously registered listener of progress events.
*
* @param aListener
* The listener interface previously registered with a call to
* addProgressListener.
*
* @throw NS_ERROR_FAILURE
* Indicates that aListener was not registered.
*/
void removeProgressListener(in nsIWebProgressListener aListener);
/**
* BrowsingContext associated with this nsIWebProgress instance, or `null` if
* there is no BrowsingContext.
*/
[binaryname(BrowsingContextXPCOM)]
readonly attribute BrowsingContext browsingContext;
[noscript,notxpcom,nostdcall] BrowsingContext getBrowsingContext();
/**
* The DOM window associated with this nsIWebProgress instance.
*
* @throw NS_ERROR_FAILURE
* Indicates that there is no associated DOM window.
*/
readonly attribute mozIDOMWindowProxy DOMWindow;
/**
* Indicates whether DOMWindow.top == DOMWindow.
*/
readonly attribute boolean isTopLevel;
/**
* Indicates whether or not a document is currently being loaded
* in the context of this nsIWebProgress instance.
*/
readonly attribute boolean isLoadingDocument;
/**
* Contains a load type as specified by the load* constants in
* nsIDocShell:LoadCommand.
*/
readonly attribute unsigned long loadType;
/**
* Main thread event target to which progress updates should be
* dispatched. This typically will be a SchedulerEventTarget
* corresponding to the tab requesting updates.
*/
attribute nsIEventTarget target;
/**
* The request for the currently loading document. It is null if
* isLoadingDocument is false.
* Note, the request may not be the actual nsIChannel instance used for
* loading, but a dummy RemoteWebProgressRequest. And since redirects are
* hidden from the child processes, this may not reflect the complete
* redirect state of the load.
*/
readonly attribute nsIRequest documentRequest;
};
