gecko-dev/docshell/base/nsIWebNavigation.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"
#include "domstubs.idl"

/**
 * The nsIWebNavigation interface defines an interface for navigating the web.
 * It provides methods and attributes to direct an object to navigate to a new
 * location, stop or restart an in process load or determine where the object,
 * has previously gone.   
 *
 * @status UNDER_REVIEW
 */
 
interface nsISHistory;				
interface nsISHEntry;
interface nsIURI;

[scriptable, uuid(F5D9E7B0-D930-11d3-B057-00A024FFC08C)]
interface nsIWebNavigation : nsISupports
{
	/*
	Indicates if the object can go back.  If true this indicates that
	there is back session history available to navigate to.
	*/
	readonly attribute boolean canGoBack;

	/*
	Indicates if the object can go forward.  If true this indicates that
	there is forward session history available to navigate to.
	*/
	readonly attribute boolean canGoForward;

	/*
	Tells the object to navigate to the next Back session history item.
	@return	NS_OK - Back was successfull
				NS_ERROR_UNEXPECTED - This call was unexpected at this time.  Most
				likely you can't go back right now.
	*/
	void goBack();

	/*
	Tells the object to navigate to the next Forward session history item.
	@return	NS_OK - Forward was successfull
				NS_ERROR_UNEXPECTED - This call was unexpected at this time.  Most
				likely you can't go forward right now.
	*/
	void goForward();

	/*
	Tells the object to navigate to the session history item at index.
	@return	NS_OK - Gotoindex was successfull
				NS_ERROR_UNEXPECTED - This call was unexpected at this time.  Most
				likely you can't goto that index
	*/
	void gotoIndex(in long index);

	/*
	Load flags for use with loadURI() and reload()
	*/
	const unsigned long LOAD_FLAGS_NONE            = 0x0000;
	const unsigned long LOAD_FLAGS_MASK            = 0xffff;

    /* loadURI() specific flags */
	const unsigned long LOAD_FLAGS_IS_REFRESH      = 0x0010; // Refresh timer
	const unsigned long LOAD_FLAGS_IS_LINK         = 0x0020; // Link click
	const unsigned long LOAD_FLAGS_BYPASS_HISTORY  = 0x0040; // Bypass the history
	const unsigned long LOAD_FLAGS_REPLACE_HISTORY = 0x0080; // Replace the history entry

    /* loadURI() & reload() specific flags */
	const unsigned long LOAD_FLAGS_BYPASS_CACHE    = 0x0100; // Bypass the cache
	const unsigned long LOAD_FLAGS_BYPASS_PROXY    = 0x0200; // Bypass the proxy

    /*
    Loads a given URI.  This will give priority to loading the requested URI
	in the object implementing	this interface.  If it can't be loaded here
	however, the URL dispatcher will go through its normal process of content
	loading.

	@param uri - The URI to load.
	@param loadFlags - Flags modifying load behaviour. Generally you will pass
	        LOAD_FLAGS_NONE for this parameter.
	*/
	void loadURI(in wstring uri, in unsigned long loadFlags);

	/*
	Tells the Object to reload the current location.
	@param reloadFlags - Flags modifying reload behaviour. Generally you will
	        pass LOAD_FLAGS_NONE for this parameter.
	*/
	void reload(in unsigned long reloadFlags);

	/*
	Stops a load of a URI.
	*/
	void stop();

	/*
	Retrieves the current Document for the WebBrowser.  When setting
	this will simulate the normal load process.
	*/
	readonly attribute nsIDOMDocument document;
	
	/*
	The current URI that is loaded.
	*/
	readonly attribute nsIURI currentURI;
	
	/*
	The session history object used to store the session history for the session.
	*/
	attribute nsISHistory sessionHistory;
};