The Tor Browser: comparison uriloader/base/nsIWebProgressListener.idl

--1:000000000000
+:6e9aafb72254
+/* -*- 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 nsIWebProgress;
+interface nsIRequest;
+interface nsIURI;
+/**
+* The nsIWebProgressListener interface is implemented by clients wishing to
+* listen in on the progress associated with the loading of asynchronous
+* requests in the context of a nsIWebProgress instance as well as any child
+* nsIWebProgress instances.  nsIWebProgress.idl describes the parent-child
+* relationship of nsIWebProgress instances.
+*/
+[scriptable, uuid(a0cda7e4-c6ca-11e0-b6a5-001320257da5)]
+interface nsIWebProgressListener : nsISupports
+{
+/**
+* State Transition Flags
+*
+* These flags indicate the various states that requests may transition
+* through as they are being loaded.  These flags are mutually exclusive.
+*
+* For any given request, onStateChange is called once with the STATE_START
+* flag, zero or more times with the STATE_TRANSFERRING flag or once with the
+* STATE_REDIRECTING flag, and then finally once with the STATE_STOP flag.
+* NOTE: For document requests, a second STATE_STOP is generated (see the
+* description of STATE_IS_WINDOW for more details).
+*
+* STATE_START
+*   This flag indicates the start of a request.  This flag is set when a
+*   request is initiated.  The request is complete when onStateChange is
+*   called for the same request with the STATE_STOP flag set.
+*
+* STATE_REDIRECTING
+*   This flag indicates that a request is being redirected.  The request
+*   passed to onStateChange is the request that is being redirected.  When a
+*   redirect occurs, a new request is generated automatically to process the
+*   new request.  Expect a corresponding STATE_START event for the new
+*   request, and a STATE_STOP for the redirected request.
+*
+* STATE_TRANSFERRING
+*   This flag indicates that data for a request is being transferred to an
+*   end consumer.  This flag indicates that the request has been targeted,
+*   and that the user may start seeing content corresponding to the request.
+*
+* STATE_NEGOTIATING
+*   This flag is not used.
+*
+* STATE_STOP
+*   This flag indicates the completion of a request.  The aStatus parameter
+*   to onStateChange indicates the final status of the request.
+*/
+const unsigned long STATE_START          = 0x00000001;
+const unsigned long STATE_REDIRECTING    = 0x00000002;
+const unsigned long STATE_TRANSFERRING   = 0x00000004;
+const unsigned long STATE_NEGOTIATING    = 0x00000008;
+const unsigned long STATE_STOP           = 0x00000010;
+/**
+* State Type Flags
+*
+* These flags further describe the entity for which the state transition is
+* occuring.  These flags are NOT mutually exclusive (i.e., an onStateChange
+* event may indicate some combination of these flags).
+*
+* STATE_IS_REQUEST
+*   This flag indicates that the state transition is for a request, which
+*   includes but is not limited to document requests.  (See below for a
+*   description of document requests.)  Other types of requests, such as
+*   requests for inline content (e.g., images and stylesheets) are
+*   considered normal requests.
+*
+* STATE_IS_DOCUMENT
+*   This flag indicates that the state transition is for a document request.
+*   This flag is set in addition to STATE_IS_REQUEST.  A document request
+*   supports the nsIChannel interface and its loadFlags attribute includes
+*   the nsIChannel::LOAD_DOCUMENT_URI flag.
+*
+*   A document request does not complete until all requests associated with
+*   the loading of its corresponding document have completed.  This includes
+*   other document requests (e.g., corresponding to HTML <iframe> elements).
+*   The document corresponding to a document request is available via the
+*   DOMWindow attribute of onStateChange's aWebProgress parameter.
+*
+* STATE_IS_NETWORK
+*   This flag indicates that the state transition corresponds to the start
+*   or stop of activity in the indicated nsIWebProgress instance.  This flag
+*   is accompanied by either STATE_START or STATE_STOP, and it may be
+*   combined with other State Type Flags.
+*
+*   Unlike STATE_IS_WINDOW, this flag is only set when activity within the
+*   nsIWebProgress instance being observed starts or stops.  If activity
+*   only occurs in a child nsIWebProgress instance, then this flag will be
+*   set to indicate the start and stop of that activity.
+*
+*   For example, in the case of navigation within a single frame of a HTML
+*   frameset, a nsIWebProgressListener instance attached to the
+*   nsIWebProgress of the frameset window will receive onStateChange calls
+*   with the STATE_IS_NETWORK flag set to indicate the start and stop of
+*   said navigation.  In other words, an observer of an outer window can
+*   determine when activity, that may be constrained to a child window or
+*   set of child windows, starts and stops.
+*
+* STATE_IS_WINDOW
+*   This flag indicates that the state transition corresponds to the start
+*   or stop of activity in the indicated nsIWebProgress instance.  This flag
+*   is accompanied by either STATE_START or STATE_STOP, and it may be
+*   combined with other State Type Flags.
+*
+*   This flag is similar to STATE_IS_DOCUMENT.  However, when a document
+*   request completes, two onStateChange calls with STATE_STOP are
+*   generated.  The document request is passed as aRequest to both calls.
+*   The first has STATE_IS_REQUEST and STATE_IS_DOCUMENT set, and the second
+*   has the STATE_IS_WINDOW flag set (and possibly the STATE_IS_NETWORK flag
+*   set as well -- see above for a description of when the STATE_IS_NETWORK
+*   flag may be set).  This second STATE_STOP event may be useful as a way
+*   to partition the work that occurs when a document request completes.
+*/
+const unsigned long STATE_IS_REQUEST     = 0x00010000;
+const unsigned long STATE_IS_DOCUMENT    = 0x00020000;
+const unsigned long STATE_IS_NETWORK     = 0x00040000;
+const unsigned long STATE_IS_WINDOW      = 0x00080000;
+/**
+* State Modifier Flags
+*
+* These flags further describe the transition which is occuring.  These
+* flags are NOT mutually exclusive (i.e., an onStateChange event may
+* indicate some combination of these flags).
+*
+* STATE_RESTORING
+*   This flag indicates that the state transition corresponds to the start
+*   or stop of activity for restoring a previously-rendered presentation.
+*   As such, there is no actual network activity associated with this
+*   request, and any modifications made to the document or presentation
+*   when it was originally loaded will still be present.
+*/
+const unsigned long STATE_RESTORING      = 0x01000000;
+/**
+* State Security Flags
+*
+* These flags describe the security state reported by a call to the
+* onSecurityChange method.  These flags are mutually exclusive.
+*
+* STATE_IS_INSECURE
+*   This flag indicates that the data corresponding to the request
+*   was received over an insecure channel.
+*
+* STATE_IS_BROKEN
+*   This flag indicates an unknown security state.  This may mean that the
+*   request is being loaded as part of a page in which some content was
+*   received over an insecure channel.
+*
+* STATE_IS_SECURE
+*   This flag indicates that the data corresponding to the request was
+*   received over a secure channel.  The degree of security is expressed by
+*   STATE_SECURE_HIGH, STATE_SECURE_MED, or STATE_SECURE_LOW.
+*/
+const unsigned long STATE_IS_INSECURE     = 0x00000004;
+const unsigned long STATE_IS_BROKEN       = 0x00000001;
+const unsigned long STATE_IS_SECURE       = 0x00000002;
+/**
+* Mixed active content flags
+*
+* May be set in addition to the State Security Flags, to indicate that
+* mixed active content has been encountered.
+*
+* STATE_BLOCKED_MIXED_ACTIVE_CONTENT
+*   Mixed active content has been blocked from loading.
+*
+* STATE_LOADED_MIXED_ACTIVE_CONTENT
+*   Mixed active content has been loaded. State should be STATE_IS_BROKEN.
+*/
+const unsigned long STATE_BLOCKED_MIXED_ACTIVE_CONTENT  = 0x00000010;
+const unsigned long STATE_LOADED_MIXED_ACTIVE_CONTENT   = 0x00000020;
+/**
+* Mixed display content flags
+*
+* May be set in addition to the State Security Flags, to indicate that
+* mixed display content has been encountered.
+*
+* STATE_BLOCKED_MIXED_DISPLAY_CONTENT
+*   Mixed display content has been blocked from loading.
+*
+* STATE_LOADED_MIXED_DISPLAY_CONTENT
+*   Mixed display content has been loaded. State should be STATE_IS_BROKEN.
+*/
+const unsigned long STATE_BLOCKED_MIXED_DISPLAY_CONTENT = 0x00000100;
+const unsigned long STATE_LOADED_MIXED_DISPLAY_CONTENT  = 0x00000200;
+/**
+* Security Strength Flags
+*
+* These flags describe the security strength and accompany STATE_IS_SECURE
+* in a call to the onSecurityChange method.  These flags are mutually
+* exclusive.
+*
+* These flags are not meant to provide a precise description of data
+* transfer security.  These are instead intended as a rough indicator that
+* may be used to, for example, color code a security indicator or otherwise
+* provide basic data transfer security feedback to the user.
+*
+* STATE_SECURE_HIGH
+*   This flag indicates a high degree of security.
+*
+* STATE_SECURE_MED
+*   This flag indicates a medium degree of security.
+*
+* STATE_SECURE_LOW
+*   This flag indicates a low degree of security.
+*/
+const unsigned long STATE_SECURE_HIGH     = 0x00040000;
+const unsigned long STATE_SECURE_MED      = 0x00010000;
+const unsigned long STATE_SECURE_LOW      = 0x00020000;
+/**
+* State bits for EV == Extended Validation == High Assurance
+*
+* These flags describe the level of identity verification
+* in a call to the onSecurityChange method.
+*
+* STATE_IDENTITY_EV_TOPLEVEL
+*   The topmost document uses an EV cert.
+*   NOTE: Available since Gecko 1.9
+*/
+const unsigned long STATE_IDENTITY_EV_TOPLEVEL    = 0x00100000;
+/**
+* Notification indicating the state has changed for one of the requests
+* associated with aWebProgress.
+*
+* @param aWebProgress
+*        The nsIWebProgress instance that fired the notification
+* @param aRequest
+*        The nsIRequest that has changed state.
+* @param aStateFlags
+*        Flags indicating the new state.  This value is a combination of one
+*        of the State Transition Flags and one or more of the State Type
+*        Flags defined above.  Any undefined bits are reserved for future
+*        use.
+* @param aStatus
+*        Error status code associated with the state change.  This parameter
+*        should be ignored unless aStateFlags includes the STATE_STOP bit.
+*        The status code indicates success or failure of the request
+*        associated with the state change.  NOTE: aStatus may be a success
+*        code even for server generated errors, such as the HTTP 404 error.
+*        In such cases, the request itself should be queried for extended
+*        error information (e.g., for HTTP requests see nsIHttpChannel).
+*/
+void onStateChange(in nsIWebProgress aWebProgress,
+in nsIRequest aRequest,
+in unsigned long aStateFlags,
+in nsresult aStatus);
+/**
+* Notification that the progress has changed for one of the requests
+* associated with aWebProgress.  Progress totals are reset to zero when all
+* requests in aWebProgress complete (corresponding to onStateChange being
+* called with aStateFlags including the STATE_STOP and STATE_IS_WINDOW
+* flags).
+*
+* @param aWebProgress
+*        The nsIWebProgress instance that fired the notification.
+* @param aRequest
+*        The nsIRequest that has new progress.
+* @param aCurSelfProgress
+*        The current progress for aRequest.
+* @param aMaxSelfProgress
+*        The maximum progress for aRequest.
+* @param aCurTotalProgress
+*        The current progress for all requests associated with aWebProgress.
+* @param aMaxTotalProgress
+*        The total progress for all requests associated with aWebProgress.
+*
+* NOTE: If any progress value is unknown, or if its value would exceed the
+* maximum value of type long, then its value is replaced with -1.
+*
+* NOTE: If the object also implements nsIWebProgressListener2 and the caller
+* knows about that interface, this function will not be called. Instead,
+* nsIWebProgressListener2::onProgressChange64 will be called.
+*/
+void onProgressChange(in nsIWebProgress aWebProgress,
+in nsIRequest aRequest,
+in long aCurSelfProgress,
+in long aMaxSelfProgress,
+in long aCurTotalProgress,
+in long aMaxTotalProgress);
+/**
+* Flags for onLocationChange
+*
+* LOCATION_CHANGE_SAME_DOCUMENT
+*   This flag is on when |aWebProgress| did not load a new document.
+*   For example, the location change is due to an anchor scroll or a
+*   pushState/popState/replaceState.
+*
+* LOCATION_CHANGE_ERROR_PAGE
+*   This flag is on when |aWebProgress| redirected from the requested
+*   contents to an internal page to show error status, such as
+*   <about:neterror>, <about:certerror> and so on.
+*
+*   Generally speaking, |aURI| and |aRequest| are the original data. DOM
+*   |window.location.href| is also the original location, while
+*   |document.documentURI| is the redirected location. Sometimes |aURI| is
+*   <about:blank> and |aRequest| is null when the original data does not
++   remain.
+*
+*   |aWebProgress| does NOT set this flag when it did not try to load a new
+*   document. In this case, it should set LOCATION_CHANGE_SAME_DOCUMENT.
+*/
+const unsigned long LOCATION_CHANGE_SAME_DOCUMENT   = 0x00000001;
+const unsigned long LOCATION_CHANGE_ERROR_PAGE      = 0x00000002;
+/**
+* Called when the location of the window being watched changes.  This is not
+* when a load is requested, but rather once it is verified that the load is
+* going to occur in the given window.  For instance, a load that starts in a
+* window might send progress and status messages for the new site, but it
+* will not send the onLocationChange until we are sure that we are loading
+* this new page here.
+*
+* @param aWebProgress
+*        The nsIWebProgress instance that fired the notification.
+* @param aRequest
+*        The associated nsIRequest.  This may be null in some cases.
+* @param aLocation
+*        The URI of the location that is being loaded.
+* @param aFlags
+*        This is a value which explains the situation or the reason why
+*        the location has changed.
+*/
+void onLocationChange(in nsIWebProgress aWebProgress,
+in nsIRequest aRequest,
+in nsIURI aLocation,
+[optional] in unsigned long aFlags);
+/**
+* Notification that the status of a request has changed.  The status message
+* is intended to be displayed to the user (e.g., in the status bar of the
+* browser).
+*
+* @param aWebProgress
+*        The nsIWebProgress instance that fired the notification.
+* @param aRequest
+*        The nsIRequest that has new status.
+* @param aStatus
+*        This value is not an error code.  Instead, it is a numeric value
+*        that indicates the current status of the request.  This interface
+*        does not define the set of possible status codes.  NOTE: Some
+*        status values are defined by nsITransport and nsISocketTransport.
+* @param aMessage
+*        Localized text corresponding to aStatus.
+*/
+void onStatusChange(in nsIWebProgress aWebProgress,
+in nsIRequest aRequest,
+in nsresult aStatus,
+in wstring aMessage);
+/**
+* Notification called for security progress.  This method will be called on
+* security transitions (eg HTTP -> HTTPS, HTTPS -> HTTP, FOO -> HTTPS) and
+* after document load completion.  It might also be called if an error
+* occurs during network loading.
+*
+* @param aWebProgress
+*        The nsIWebProgress instance that fired the notification.
+* @param aRequest
+*        The nsIRequest that has new security state.
+* @param aState
+*        A value composed of the Security State Flags and the Security
+*        Strength Flags listed above.  Any undefined bits are reserved for
+*        future use.
+*
+* NOTE: These notifications will only occur if a security package is
+* installed.
+*/
+void onSecurityChange(in nsIWebProgress aWebProgress,
+in nsIRequest aRequest,
+in unsigned long aState);
+};

The Tor Browser / file comparison

comparison: uriloader/base/nsIWebProgressListener.idl

uriloader/base/nsIWebProgressListener.idl