toolkit/components/places/public/nsINavHistoryService.idlScriptable
A foundation for the interfaces that provide a description of a query result on the Places service that describes a container (which is any kind of grouping, including bookmark folders).
1.0
66
Introduced
Gecko 1.9
Inherits from: nsINavHistoryResultNode Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

Method overview

nsINavHistoryResultNode findNodeByDetails(in AUTF8String aURIString, in PRTime aTime, in long long aItemId, in boolean aRecursive);
nsINavHistoryResultNode getChild(in unsigned long aIndex);
unsigned long getChildIndex(in nsINavHistoryResultNode aNode);

Attributes

Attribute Type Description
childCount unsigned long The number of child nodes; accessing this throws an NS_ERROR_NOT_AVAILABLE exception of containerOpen is false. Read only.
childrenReadOnly boolean false if the node's list of children can be modified (by adding or removing children, or rearranging them), or true if the user interface should not allow the list of children to be altered. Read-only.

This is false for bookmark folder nodes unless the setFolderReadOnly() method has been called to specifically make the folder read-only. It's true for non-folder nodes.

If this container is a remote container, this flag may be redefined by the remote container provider. Read-only.
containerOpen boolean Set this to true to allow descent into this container. When closed, attempting to call getChild() or access childCount results in an error. When you're done reading the container's children, set this to false.

For HOST and DAY groupings, doing this has no performance cost since the children have already been computed. For queries and bookmark folders, however, being open means they must keep themselves up-to-date by listening for updates and re-querying as needed.
dynamicContainerType AUTF8String A string representing the dynamic container API service responsible for this container. Accessing this throws an exception if the node isn't a dynamic container. Read only.
hasChildren boolean Indicates whether or not the node can have children, and may be used whether the container is open or closed. When the container is closed, the result is an exact answer if the node can be populated easily (for example, for bookmark folders). If it can't be populated easily (for complex history queries, for example), the result is always true.

When the container is open, the result is always accurate.

This value is intended to be used to see if the "+" should be drawn next to a tree item, indicating that the item can be opened. Read-only.
remoteContainerType Obsolete since Gecko 1.9 AUTF8String A string representing the remote container service API that is responsible for this container. If there is no such API, this value is an empty string. Read only.

The container may be a RESULT_TYPE_REMOTE_CONTAINER node that has been dynamically generated by the remote container API, or a bookmark folder (RESULT_TYPE_FOLDER) for which some service (such as livemarks) has registered to provide certain operations.
state unsigned short The current state of the container. This is one of the state constants.

Constants

State constants

Constant Value Description
STATE_CLOSED
0 The container is closed.
STATE_LOADING
1 The container has been opened asynchronously, but is still loading and is not all the way opened yet.
STATE_OPENED
2 The container is open.

Methods

findNodeByDetails()

Returns a node matching specified details.

nsINavHistoryResultNode findNodeByDetails(
  in AUTF8String aURIString,
  in PRTime aTime,
  in long long aItemId,
  in boolean recursive
);
Parameters
aURIString
The URI attribute value to match on.
aTime
The time attribute to match on.
aItemId
The item ID to match on.
aRecursive
If true, the search will recurse through all child containers of the current container; if false, only direct children of the container are searched.
Return value

An nsINavHistoryResultNode of a node matching the specified details or null if no match is found.

Exceptions thrown
NS_ERROR_NOT_AVAILABLE
The container is not open.

getChild()

Returns the child node at the specified index.

 nsINavHistoryResultNode getChild(
   in unsigned long aIndex
 );
Parameters
aIndex
The index into the child list of the node to fetch.
Returns

The node located at the specified index.

Exceptions thrown
NS_ERROR_NOT_AVAILABLE
The containerOpen attribute is currently false, indicating that the node isn't open for access.

getChildIndex()

Returns the index of a direct child of this container.

unsigned long getChildIndex(
  in nsINavHistoryResultNode aNode
);
Parameters
aNode
The node whose index is to be returned.
Return value

The index of the specified node into the list of immediate children of the container.

Exceptions thrown
NS_ERROR_NOT_AVAILABLE
The container isn't open (that is, containerOpen is false).
NS_ERROR_INVALID_ARG
The specified node isn't a direct child of this container.

Remarks

There are a number of untested methods on this interface that are not documented at present, and are disabled in the idl file.

See also

nsINavHistoryResultNode, nsINavHistoryService