gecko-dev/uriloader/base/nsIWebProgress.idl

/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/MPL/
 * 
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 * 
 * The Original Code is the Mozilla browser.
 * 
 * The Initial Developer of the Original Code is Netscape
 * Communications, Inc.  Portions created by Netscape are
 * Copyright (C) 1999, Mozilla.  All Rights Reserved.
 * 
 * Contributor(s):
 *   Travis Bogard <travis@netscape.com>
 */

#include "nsISupports.idl"

interface nsIWebProgressListener;

/**
 * The nsIWebProgress interface is used to look at the progress of a given 
 * browser loading.
 */

[scriptable, uuid(570F39D0-EFD0-11d3-B093-00A024FFC08C)]
interface nsIWebProgress : nsISupports
{	
	/*
	Progress Status Flags

	flag_net_dns - Looking up requested host.
	flag_net_connecting - Connecting to requested host.
	flag_net_redirecting - Connection is being redirected.
	flag_net_negotiating - Negotiating connection to the server 
		(Authentication/ Authorization).
	flag_net_transferring - Transferring data from host.

	flag_net_failed - When set this means the load failed.  When off this means
	  the load is either continuing with success (flag_networkActivity = 1) 
	  or that the load has completed successfully (flag_networkActivity = 0)

	flag_net_failedDNS - DNS lookup failed.
	flag_net_failedConnect - Connecting to server failed.
	flag_net_failedTransfer - Transfer failed.
	flag_net_userCancelled - User cancelled load.
	*/	
	const long flag_net_dns					= 0x00000001;
	const long flag_net_connecting		= 0x00000002;
	const long flag_net_redirecting		= 0x00000004;
	const long flag_net_negotiating		= 0x00000008;
	const long flag_net_transferring		= 0x00000010;

	const long flag_net_failed				= 0x20000000;
	const long flag_net_failedDNS			= 0x00010000 | flag_net_failed;
	const long flag_net_failedConnect	= 0x00020000 | flag_net_failed;
	const long flag_net_failedTransfer	= 0x00040000 | flag_net_failed;
	const long flag_net_userCancelled	= 0x00080000 | flag_net_failed;
	const long flag_networkActivity		= 0x40000000;
	const long flag_windowActivity		= 0x80000000;

	/*
	Registers a listener to be notified of Progress Events

	@param listener - The listener interface to be called when a progress event
			occurs.

	@param cookie - This is an optional parameter to receieve a cookie to use
			to unregister rather than the original interface pointer.  This may
			be nsnull.

	@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.
	 */
	void addProgressListener(in nsIWebProgressListener listener, out long cookie);

	/* 
	Removes a previously registered listener of Progress Events
		
	@param listener - The listener interface previously registered with 
			AddListener() this may be nsnull if a valid cookie is provided.

	@param cookie - A cookie that was returned from a previously called
		AddListener() call.  This may be nsnull if a valid listener interface
		is passed in.

	@return	NS_OK - Listener was successfully unregistered.
				NS_ERROR_INVALID_ARG - Neither the cookie nor the listener point
					to a previously registered listener.
	*/
	void removeProgressListener(in nsIWebProgressListener listener, in long cookie);

	/*
	Current progress Status of the browser.  This will be a combination of the 
	progress status flags.
	*/
	readonly attribute long progressStatusFlags;

	/*
	The current position of progress.  This is between 0 and maxSelfProgress.
	This is the position of only this progress object.  It doesn not include
	the progress of all children.
	*/
	readonly attribute long curSelfProgress;

	/*
	The maximum position that progress will go to.  This sets a relative
	position point for the current progress to relate to.  This is the max
	position of only this progress object.  It does not include the progress of
	all the children.
	*/
	readonly attribute long maxSelfProgress;

	/*
	The current position of progress for this object and all children added
	together.  This is between 0 and maxTotalProgress.
	*/
	readonly attribute long curTotalProgress;

	/*
	The maximum position that progress will go to for the max of this progress
	object and all children.  This sets the relative position point for the
	current progress to relate to.
	*/
	readonly attribute long maxTotalProgress;
};