import FIREFOX_52_6_0esr_RELEASE from mozilla-esr52 hg repo

docshell/base/nsIDocShellTreeItem.idl

@@ -0,0 +1,184 @@
+/* -*- 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 nsIDocShellTreeOwner;
+interface nsIDocument;
+interface nsPIDOMWindowOuter;
+
+
+/**
+ * The nsIDocShellTreeItem supplies the methods that are required of any item
+ * that wishes to be able to live within the docshell tree either as a middle
+ * node or a leaf. 
+ */
+
+[scriptable, uuid(9b7c586f-9214-480c-a2c4-49b526fff1a6)]
+interface nsIDocShellTreeItem : nsISupports
+{
+	/*
+	name of the DocShellTreeItem
+	*/
+	attribute AString name;
+
+        /**
+         * Compares the provided name against the item's name and
+         * returns the appropriate result.
+         *
+         * @return <CODE>PR_TRUE</CODE> if names match;
+         *         <CODE>PR_FALSE</CODE> otherwise.
+         */
+        boolean nameEquals(in AString name);
+
+	/*
+	Definitions for the item types.
+	*/
+	const long typeChrome=0;            // typeChrome must equal 0
+	const long typeContent=1;           // typeContent must equal 1
+	const long typeContentWrapper=2;    // typeContentWrapper must equal 2
+	const long typeChromeWrapper=3;     // typeChromeWrapper must equal 3
+
+	const long typeAll=0x7FFFFFFF;
+
+	/*
+	The type this item is.  
+	*/
+	attribute long itemType;
+	[noscript,notxpcom,nostdcall] long ItemType();
+
+	/*
+	Parent DocShell.
+	*/
+	readonly attribute nsIDocShellTreeItem parent;
+
+	/*
+	This getter returns the same thing parent does however if the parent
+	is of a different itemType, or if the parent is an <iframe mozbrowser>
+	or <iframe mozapp>, it will instead return nullptr.  This call is a
+	convience function for those wishing to not cross the boundaries at
+	which item types change.
+	*/
+	readonly attribute nsIDocShellTreeItem sameTypeParent;
+
+	/*
+	Returns the root DocShellTreeItem.  This is a convience equivalent to 
+	getting the parent and its parent until there isn't a parent.
+	*/
+	readonly attribute nsIDocShellTreeItem rootTreeItem;
+
+	/*
+	Returns the root DocShellTreeItem of the same type.  This is a convience 
+	equivalent to getting the parent of the same type and its parent until 
+	there isn't a parent.
+	*/
+	readonly attribute nsIDocShellTreeItem sameTypeRootTreeItem;
+
+	/*
+	Returns the docShellTreeItem with the specified name.  Search order is as 
+	follows...
+	1.)  Check name of self, if it matches return it.
+	2.)  For each immediate child.
+		a.) Check name of child and if it matches return it.
+		b.)  Ask the child to perform the check
+			i.) Do not ask a child if it is the aRequestor
+			ii.) Do not ask a child if it is of a different item type.
+	3.)  If there is a parent of the same item type ask parent to perform the check
+		a.) Do not ask parent if it is the aRequestor
+	4.)  If there is a tree owner ask the tree owner to perform the check
+		a.)  Do not ask the tree owner if it is the aRequestor
+		b.)  This should only be done if there is no parent of the same type.
+
+	Return the child DocShellTreeItem with the specified name.
+	name - This is the name of the item that is trying to be found.
+	aRequestor - This is the object that is requesting the find.  This
+		parameter is used to identify when the child is asking its parent to find
+		a child with the specific name.  The parent uses this parameter to ensure
+		a resursive state does not occur by not again asking the requestor to find
+		a shell by the specified name.  Inversely the child uses it to ensure it
+		does not ask its parent to do the search if its parent is the one that
+		asked it to search.  Children also use this to test against the treeOwner;
+	aOriginalRequestor - The original treeitem that made the request, if any.
+		This is used to ensure that we don't run into cross-site issues.
+	*/
+	nsIDocShellTreeItem findItemWithName(in AString name,
+	                                     in nsISupports aRequestor,
+	                                     in nsIDocShellTreeItem aOriginalRequestor);
+
+	/*
+	The owner of the DocShell Tree.  This interface will be called upon when
+	the docshell has things it needs to tell to the owner of the docshell.
+	Note that docShell tree ownership does not cross tree types.  Meaning
+	setting ownership on a chrome tree does not set ownership on the content 
+	sub-trees.  A given tree's boundaries are identified by the type changes.
+	Trees of different types may be connected, but should not be traversed
+	for things such as ownership.
+	
+	Note implementers of this interface should NOT effect the lifetime of the 
+	parent DocShell by holding this reference as it creates a cycle.  Owners
+	when releasing this interface should set the treeOwner to nullptr.
+	Implementers of this interface are guaranteed that when treeOwner is
+	set that the poitner is valid without having to addref.
+	
+	Further note however when others try to get the interface it should be 
+	addref'd before handing it to them. 
+	*/
+	readonly attribute nsIDocShellTreeOwner treeOwner;
+	[noscript] void setTreeOwner(in nsIDocShellTreeOwner treeOwner);
+
+	/*
+	The current number of DocShells which are immediate children of the 
+	this object.
+	*/
+	readonly attribute long childCount;
+
+	/*
+	Add a new child DocShellTreeItem.  Adds to the end of the list.
+	Note that this does NOT take a reference to the child.  The child stays
+	alive only as long as it's referenced from outside the docshell tree.
+	@throws NS_ERROR_ILLEGAL_VALUE if child corresponds to the same
+	        object as this treenode or an ancestor of this treenode
+	@throws NS_ERROR_UNEXPECTED if this node is a leaf in the tree.
+	*/
+	void addChild(in nsIDocShellTreeItem child);
+
+	/*
+	Removes a child DocShellTreeItem.
+	@throws NS_ERROR_UNEXPECTED if this node is a leaf in the tree.
+	*/
+	void removeChild(in nsIDocShellTreeItem child);
+
+	/**
+	 * Return the child at the index requested.  This is 0-based.
+	 *
+	 * @throws NS_ERROR_UNEXPECTED if the index is out of range
+	 */
+	nsIDocShellTreeItem getChildAt(in long index);
+
+	/*
+	Return the child DocShellTreeItem with the specified name.
+	aName - This is the name of the item that is trying to be found.
+	aRecurse - Is used to tell the function to recurse through children.
+		Note, recursion will only happen through items of the same type.
+	aSameType - If this is set only children of the same type will be returned.
+	aRequestor - This is the docshellTreeItem that is requesting the find.  This
+		parameter is used when recursion is being used to avoid searching the same
+		tree again when a child has asked a parent to search for children.
+	aOriginalRequestor - The original treeitem that made the request, if any.
+    	This is used to ensure that we don't run into cross-site issues.
+
+	Note the search is depth first when recursing.
+	*/
+	nsIDocShellTreeItem findChildWithName(in AString aName,
+	                                      in boolean aRecurse,
+	                                      in boolean aSameType,
+	                                      in nsIDocShellTreeItem aRequestor,
+	                                      in nsIDocShellTreeItem aOriginalRequestor);
+
+  [noscript,nostdcall,notxpcom] nsIDocument getDocument();
+  [noscript,nostdcall,notxpcom] nsPIDOMWindowOuter getWindow();
+};
+