зеркало из https://github.com/mozilla/gecko-dev.git
documentation cleanup in preparation for freezing these interfaces, b=99639
This commit is contained in:
darin%meer.net
Родитель
dfa85f90dd
Коммит
7c4f3d015a
|
|
@ -22,6 +22,7 @@
|
|||
*
|
||||
* Contributor(s):
|
||||
* Travis Bogard <travis@netscape.com>
|
||||
* Darin Fisher <darin@meer.net>
|
||||
*
|
||||
* Alternatively, the contents of this file may be used under the terms of
|
||||
* either of the GNU General Public License Version 2 or later (the "GPL"),
|
||||
|
|
@ -44,62 +45,111 @@ interface nsIWebProgressListener;
|
|||
|
||||
/**
|
||||
* The nsIWebProgress interface is used to look at the progress of document
|
||||
* loading in a particular DOM Window.
|
||||
* loading in a particular DOM window.
|
||||
*
|
||||
* @status UNDER_REVIEW
|
||||
*/
|
||||
|
||||
[scriptable, uuid(570F39D0-EFD0-11d3-B093-00A024FFC08C)]
|
||||
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.
|
||||
*/
|
||||
const unsigned long NOTIFY_PROGRESS = 0x00000010;
|
||||
const unsigned long NOTIFY_STATUS = 0x00000020;
|
||||
const unsigned long NOTIFY_SECURITY = 0x00000040;
|
||||
const unsigned long NOTIFY_LOCATION = 0x00000080;
|
||||
|
||||
/**
|
||||
* This flag enables all notifications.
|
||||
*/
|
||||
const unsigned long NOTIFY_ALL = 0x000000ff;
|
||||
|
||||
/**
|
||||
* Registers a listener to be notified of Progress Events
|
||||
* Registers a listener to receive web progress events.
|
||||
*
|
||||
* @param listener - The listener interface to be called when a progress
|
||||
* event occurs.
|
||||
* @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.
|
||||
*
|
||||
* @param aNotifyMask - The types of notifications to receive.
|
||||
*
|
||||
* @return NS_OK - Listener was registered successfully.
|
||||
* NS_INVALID_ARG - The listener passed in was either nsnull,
|
||||
* or was already registered with this progress
|
||||
* interface.
|
||||
* @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 listener,
|
||||
void addProgressListener(in nsIWebProgressListener aListener,
|
||||
in unsigned long aNotifyMask);
|
||||
|
||||
/**
|
||||
* Removes a previously registered listener of Progress Events
|
||||
* Removes a previously registered listener of progress events.
|
||||
*
|
||||
* @param listener - The listener interface previously registered with
|
||||
* AddListener().
|
||||
* @param aListener
|
||||
* The listener interface previously registered with a call to
|
||||
* addProgressListener.
|
||||
*
|
||||
* @return NS_OK - Listener was successfully unregistered.
|
||||
* NS_ERROR_INVALID_ARG - The listener was not previously
|
||||
* registered listener.
|
||||
* @throw NS_ERROR_FAILURE
|
||||
* Indicates that aListener was not registered.
|
||||
*/
|
||||
void removeProgressListener(in nsIWebProgressListener listener);
|
||||
void removeProgressListener(in nsIWebProgressListener aListener);
|
||||
|
||||
/**
|
||||
* The DOM Window associated with the WebProgress instance.
|
||||
* The nsIDOMWindow associated with this nsIWebProgress instance.
|
||||
*/
|
||||
readonly attribute nsIDOMWindow DOMWindow;
|
||||
|
||||
/**
|
||||
* The IsLoadingDocument associated with the WebProgress instance
|
||||
* Indicates whether or not a document is currently being loaded.
|
||||
*/
|
||||
readonly attribute PRBool isLoadingDocument;
|
||||
};
|
||||
|
|
|
|||
|
|
@ -22,6 +22,7 @@
|
|||
*
|
||||
* Contributor(s):
|
||||
* Travis Bogard <travis@netscape.com>
|
||||
* Darin Fisher <darin@meer.net>
|
||||
*
|
||||
* Alternatively, the contents of this file may be used under the terms of
|
||||
* either of the GNU General Public License Version 2 or later (the "GPL"),
|
||||
|
|
@ -39,44 +40,104 @@
|
|||
|
||||
#include "nsISupports.idl"
|
||||
|
||||
/**
|
||||
* The nsIWebProgressListener interface is implemented by clients wishing to
|
||||
* listen in on the progress associated with the loading of documents.
|
||||
*
|
||||
* @status UNDER_REVIEW
|
||||
*/
|
||||
|
||||
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 documents.
|
||||
*
|
||||
* @status UNDER_REVIEW
|
||||
*/
|
||||
[scriptable, uuid(570F39D1-EFD0-11d3-B093-00A024FFC08C)]
|
||||
interface nsIWebProgressListener : nsISupports
|
||||
{
|
||||
/**
|
||||
* Progress state transition bits.
|
||||
* These flags indicate the various states that documents and requests
|
||||
* may transition through as they are being loaded.
|
||||
*/
|
||||
/**
|
||||
* State Transition Flags
|
||||
*
|
||||
* These flags indicate the various states that documents and requests may
|
||||
* transition through as they are being loaded. These flags are mutually
|
||||
* exclusive.
|
||||
*
|
||||
* STATE_START
|
||||
* This flag indicates the start of a request.
|
||||
*
|
||||
* STATE_REDIRECTING
|
||||
* This flag indicates that a request 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.
|
||||
*/
|
||||
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;
|
||||
|
||||
/**
|
||||
* Progress State type bits.
|
||||
* These flags indicate whether the transition is occuring on a document
|
||||
* or an individual request within the document.
|
||||
*/
|
||||
|
||||
/**
|
||||
* 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 non-document
|
||||
* request (e.g., an inline image request).
|
||||
*
|
||||
* STATE_IS_DOCUMENT
|
||||
* This flag indicates that the state transition is for a document request,
|
||||
* which includes documents in sub-frames.
|
||||
*
|
||||
* STATE_IS_NETWORK
|
||||
* This flag indicates that the state transition corresponds to a network
|
||||
* level event. A nsIWebProgressListener attached to a nsIWebProgress will
|
||||
* not see this flag for onStateChange events corresponding to a
|
||||
* subdocument.
|
||||
*
|
||||
* STATE_IS_WINDOW
|
||||
* This flag indicates that the state transition corresponds to the DOM
|
||||
* window associated with the nsIWebProgress instance.
|
||||
*/
|
||||
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;
|
||||
|
||||
/**
|
||||
* Security state bits
|
||||
*/
|
||||
|
||||
/**
|
||||
* State Security Flags
|
||||
*
|
||||
* A combination of these flags comprises the aState parameter 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;
|
||||
|
|
@ -86,101 +147,116 @@ interface nsIWebProgressListener : nsISupports
|
|||
const unsigned long STATE_SECURE_LOW = 0x00020000;
|
||||
|
||||
|
||||
/**
|
||||
* Notification indicating the state has changed for one of the requests
|
||||
* associated with the document loaded.
|
||||
*
|
||||
* @param aWebProgress The nsIWebProgress instance that fired the
|
||||
* notification
|
||||
*
|
||||
* @param aRequest The nsIRequest which has changed state.
|
||||
*
|
||||
* @param aStateFlags Flags indicating the state change.
|
||||
*
|
||||
* @param aStatus Error status code associated with the state change.
|
||||
* This parameter should be ignored unless the status flag includes the
|
||||
* STATE_STOP bit. The status code will indicate success / failure of the
|
||||
* request associated with the state change.
|
||||
*
|
||||
* @return NS_OK should always be returned.
|
||||
*/
|
||||
/**
|
||||
* Notification indicating the state has changed for one of the requests
|
||||
* associated with the document being loaded.
|
||||
*
|
||||
* @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.
|
||||
* @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 will indicate success / failure of the request
|
||||
* associated with the state change.
|
||||
*/
|
||||
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 being
|
||||
* monitored.
|
||||
*
|
||||
* @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. If this
|
||||
* value is not known then -1 is passed.
|
||||
*
|
||||
* @param aCurTotalProgress The current progress for all the requests
|
||||
* being monitored.
|
||||
*
|
||||
* @param aMaxTotalProgress The total progress for all the requests being
|
||||
* monitored. If this value is not known then
|
||||
* -1 is passed.
|
||||
*
|
||||
* @return NS_OK should always be returned.
|
||||
*/
|
||||
/**
|
||||
* Notification that the progress has changed for one of the requests being
|
||||
* monitored.
|
||||
*
|
||||
* @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. If this value is not known then
|
||||
* -1 is passed.
|
||||
* @param aCurTotalProgress
|
||||
* The current progress for all the requests being monitored.
|
||||
* @param aMaxTotalProgress
|
||||
* The total progress for all the requests being monitored. If this
|
||||
* value is not known then -1 is passed.
|
||||
*
|
||||
* NOTE: For download sizes that exceed the maximum value representable by
|
||||
* type long, -1 will be used.
|
||||
*/
|
||||
void onProgressChange(in nsIWebProgress aWebProgress,
|
||||
in nsIRequest aRequest,
|
||||
in long aCurSelfProgress,
|
||||
in long aMaxSelfProgress,
|
||||
in long aCurTotalProgress,
|
||||
in long aMaxTotalProgress);
|
||||
/**
|
||||
* Called when the window being watched changes the location that is currently.
|
||||
* 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 we are loading
|
||||
* this new page here.
|
||||
*
|
||||
* @param location The URI of the location that is being loaded.
|
||||
*
|
||||
* @return NS_OK should always be returned.
|
||||
*/
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
void onLocationChange(in nsIWebProgress aWebProgress,
|
||||
in nsIRequest aRequest,
|
||||
in nsIURI location);
|
||||
in nsIURI aLocation);
|
||||
|
||||
/**
|
||||
* Notification that the status has changed. The status message is usually
|
||||
* printed in the status bar of the browser.
|
||||
*
|
||||
* @return NS_OK should always be returned.
|
||||
*/
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* These notification will only occur if a security package is installed.
|
||||
*
|
||||
* @return NS_OK should always be returned.
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* NOTE: These notification will only occur if a security package is
|
||||
* installed.
|
||||
*
|
||||
* @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 listed above.
|
||||
*/
|
||||
void onSecurityChange(in nsIWebProgress aWebProgress,
|
||||
in nsIRequest aRequest,
|
||||
in unsigned long state);
|
||||
in unsigned long aState);
|
||||
};
|
||||
|
||||
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче