/* -*- 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 nsIProgressListener;

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

[scriptable, uuid(69E5DF04-7B8B-11d3-AF61-00A024FFC08C)]
interface nsIProgress : nsISupports
{	
	/*
	Connection Status Steps

	step_dns - Looking up requested host.
	step_connecting - Connecting to requested host.
	step_negotiating - Negotiating connection to the server 
		(Authentication/ Authorization).
	step_transferring - Transferring data from host.
	step_done - All completed successfully.
	step_failedDNS - DNS lookup failed.
	step_failedConnect - Connecting to server failed.
	step_failedTranfer - Transfer failed.
	step_userCancelled - User cancelled load.
	*/	
	const long step_dns = 1;
	const long step_connecting = 2;
	const long step_negotiating = 3;
	const long step_transferring = 4;
	const long step_done = 5;
	const long step_failedDNS = 6;
	const long step_failedConnect = 7;
	const long step_failedTransfer = 8;
	const long step_userCancelled = 9;

	/*
	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 nsIProgressListener 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 nsIProgressListener listener, in long cookie);

	/*
	Current connection Status of the browser.  This will be one of the enumerated
	connection progress steps.
	*/
	readonly attribute long connectionStatus;

	/*
	Simple boolean to know if the browser is active or not.  This provides the 
	same information that the connectionStatus attribute does.  This however
	allows you to avoid having to check the various connection steps.
	*/
	readonly attribute boolean active;

	/*
	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;

	/*
	Retrieves the progress object for a particular child part.

	@param childPart - The number of the child part you wish to retrieve.
	@param childProgress - The returned progress interface for the requested
		child.
	*/
	void getChildPart(in long childPart, out nsIProgress childProgress);

	/*
	Number of Child progress parts.
	*/
	readonly attribute long numChildParts;
};
