The Tor Browser / file revision

 /* -*- Mode: IDL; tab-width: 2; 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/. */

 /**

  * Using Places services after quit-application is not reliable, so make

  * sure to do any shutdown work on quit-application, or history

  * synchronization could fail, losing latest changes.

  */

 #include "nsISupports.idl"

 interface nsIArray;

 interface nsIURI;

 interface nsIVariant;

 interface nsIFile;

 interface nsINavHistoryContainerResultNode;

 interface nsINavHistoryQueryResultNode;

 interface nsINavHistoryQuery;

 interface nsINavHistoryQueryOptions;

 interface nsINavHistoryResult;

 interface nsINavHistoryBatchCallback;

 [scriptable, uuid(91d104bb-17ef-404b-9f9a-d9ed8de6824c)]

 interface nsINavHistoryResultNode : nsISupports

 {

   /**

    * Indentifies the parent result node in the result set. This is null for

    * top level nodes.

    */

   readonly attribute nsINavHistoryContainerResultNode parent;

   /**

    * The history-result to which this node belongs.

    */

   readonly attribute nsINavHistoryResult parentResult;

   /**

    * URI of the resource in question. For visits and URLs, this is the URL of

    * the page. For folders and queries, this is the place: URI of the

    * corresponding folder or query. This may be empty for other types of

    * objects like host containers.

    */

   readonly attribute AUTF8String uri;

   /**

    * Identifies the type of this node. This node can then be QI-ed to the

    * corresponding specialized result node interface.

    */

   const unsigned long RESULT_TYPE_URI = 0;               // nsINavHistoryResultNode

   // Visit nodes are deprecated and unsupported.

   // This line exists just to avoid reusing the value:

   // const unsigned long RESULT_TYPE_VISIT = 1;

   // Full visit nodes are deprecated and unsupported.

   // This line exists just to avoid reusing the value:

   // const unsigned long RESULT_TYPE_FULL_VISIT = 2;

   // Dynamic containers are deprecated and unsupported.

   // This const exists just to avoid reusing the value:

   // const unsigned long RESULT_TYPE_DYNAMIC_CONTAINER = 4; // nsINavHistoryContainerResultNode

   const unsigned long RESULT_TYPE_QUERY = 5;             // nsINavHistoryQueryResultNode

   const unsigned long RESULT_TYPE_FOLDER = 6;            // nsINavHistoryQueryResultNode

   const unsigned long RESULT_TYPE_SEPARATOR = 7;         // nsINavHistoryResultNode

   const unsigned long RESULT_TYPE_FOLDER_SHORTCUT = 9;   // nsINavHistoryQueryResultNode

   readonly attribute unsigned long type;

   /**

    * Title of the web page, or of the node's query (day, host, folder, etc)

    */

   readonly attribute AUTF8String title;

   /**

    * Total number of times the URI has ever been accessed. For hosts, this

    * is the total of the children under it, NOT the total times the host has

    * been accessed (this would require an additional query, so is not given

    * by default when most of the time it is never needed).

    */

   readonly attribute unsigned long accessCount;

   /**

    * This is the time the user accessed the page.

    *

    * If this is a visit, it is the exact time that the page visit occurred.

    *

    * If this is a URI, it is the most recent time that the URI was visited.

    * Even if you ask for all URIs for a given date range long ago, this might

    * contain today's date if the URI was visited today.

    *

    * For hosts, or other node types with children, this is the most recent

    * access time for any of the children.

    *

    * For days queries this is the respective endTime - a maximum possible

    * visit time to fit in the day range.

    */

   readonly attribute PRTime time;

   /**

    * This URI can be used as an image source URI and will give you the favicon

    * for the page. It is *not* the URI of the favicon, but rather something

    * that will resolve to the actual image.

    *

    * In most cases, this is an annotation URI that will query the favicon

    * service. If the entry has no favicon, this is the chrome URI of the

    * default favicon. If the favicon originally lived in chrome, this will

    * be the original chrome URI of the icon.

    */

   readonly attribute AUTF8String icon;

   /**

    * This is the number of levels between this node and the top of the

    * hierarchy. The members of result.children have indentLevel = 0, their

    * children have indentLevel = 1, etc. The indent level of the root node is

    * set to -1.

    */

   readonly attribute long indentLevel;

   /**

    * When this item is in a bookmark folder (parent is of type folder), this is

    * the index into that folder of this node. These indices start at 0 and

    * increase in the order that they appear in the bookmark folder. For items

    * that are not in a bookmark folder, this value is -1.

    */

   readonly attribute long bookmarkIndex;

   /**

    * If the node is an item (bookmark, folder or a separator) this value is the

    * row ID of that bookmark in the database. For other nodes, this value is

    * set to -1.

    */

   readonly attribute long long itemId;

   /**

    * If the node is an item (bookmark, folder or a separator) this value is the 

    * time that the item was created. For other nodes, this value is 0.

    */

   readonly attribute PRTime dateAdded;

   /**

    * If the node is an item (bookmark, folder or a separator) this value is the 

    * time that the item was last modified. For other nodes, this value is 0.

    *

    *  @note When an item is added lastModified is set to the same value as

    *        dateAdded.

    */

   readonly attribute PRTime lastModified;

   /**

    * For uri nodes, this is a sorted list of the tags, delimited with commans,

    * for the uri represented by this node. Otherwise this is an empty string.

    */

   readonly attribute AString tags;

   /**

    * The unique ID associated with the page. It my return an empty string

    * if the result node is a non-URI node.

    */

   readonly attribute ACString pageGuid;

   /**

    * The unique ID associated with the bookmark. It returns an empty string

    * if the result node is not associated with a bookmark, a folder or a

    * separator.

    */

   readonly attribute ACString bookmarkGuid;

 };

 /**

  * Base class for container results. This includes all types of groupings.

  * Bookmark folders and places queries will be QueryResultNodes which extends

  * these items.

  */

 [scriptable, uuid(5bac9734-c0ff-44eb-8d19-da88462ff6da)]

 interface nsINavHistoryContainerResultNode : nsINavHistoryResultNode

 {

   /**

    * Set this to allow descent into the container. When closed, attempting

    * to call getChildren or childCount will result in an error. You should

    * set this to false when you are done reading.

    *

    * For HOST and DAY groupings, doing this is free since the children have

    * been precomputed. For queries and bookmark folders, being open means they

    * will keep themselves up-to-date by listening for updates and re-querying

    * as needed.

    */

   attribute boolean containerOpen;

   /**

    * Indicates whether the container is closed, loading, or opened.  Loading

    * implies that the container has been opened asynchronously and has not yet

    * fully opened.

    */

   readonly attribute unsigned short state;

   const unsigned short STATE_CLOSED = 0;

   const unsigned short STATE_LOADING = 1;

   const unsigned short STATE_OPENED = 2;

   /**

    * This indicates whether this node "may" have children, and can be used

    * when the container is open or closed. When the container is closed, it

    * will give you an exact answer if the node can easily be populated (for

    * example, a bookmark folder). If not (for example, a complex history query),

    * it will return true. When the container is open, it will always be

    * accurate. It is intended to be used to see if we should draw the "+" next

    * to a tree item.

    */

   readonly attribute boolean hasChildren;

   /**

    * This gives you the children of the nodes. It is preferrable to use this

    * interface over the array one, since it avoids creating an nsIArray object

    * and the interface is already the correct type.

    *

    * @throws NS_ERROR_NOT_AVAILABLE if containerOpen is false.

    */

   readonly attribute unsigned long childCount;

   nsINavHistoryResultNode getChild(in unsigned long aIndex);

   /**

    * Get the index of a direct child in this container.

    *

    * @param aNode

    *        a result node.

    *

    * @return aNode's index in this container.

    * @throws NS_ERROR_NOT_AVAILABLE if containerOpen is false.

    * @throws NS_ERROR_INVALID_ARG if aNode isn't a direct child of this

    * container.

    */

   unsigned long getChildIndex(in nsINavHistoryResultNode aNode);

   /**

    * Look for a node in the container by some of its details.  Does not search

    * closed containers.

    *

    * @param aURI

    *        the node's uri attribute value

    * @param aTime

    *        the node's time attribute value.

    * @param aItemId

    *        the node's itemId attribute value.

    * @param aRecursive

    *        whether or not to search recursively.

    *

    * @throws NS_ERROR_NOT_AVAILABLE if this container is closed.

    * @return a result node that matches the given details if any, null

    *         otherwise.

    */

   nsINavHistoryResultNode findNodeByDetails(in AUTF8String aURIString,

                                             in PRTime aTime,

                                             in long long aItemId,

                                             in boolean aRecursive);

   /**

    * Returns false if this node's list of children can be modified

    * (adding or removing children, or reordering children), or true if

    * the UI should not allow the list of children to be modified.

    * This is false for bookmark folder nodes unless setFolderReadOnly() has

    * been called to override it, and true for non-folder nodes.

    */

   readonly attribute boolean childrenReadOnly;

 };

 /**

  * Used for places queries and as a base for bookmark folders.

  *

  * Note that if you request places to *not* be expanded in the options that

  * generated this node, this item will report it has no children and never try

  * to populate itself.

  */

 [scriptable, uuid(a4144c3e-8125-46d5-a719-831bec8095f4)]

 interface nsINavHistoryQueryResultNode : nsINavHistoryContainerResultNode

 {

   /**

    * Get the queries which build this node's children.

    * Only valid for RESULT_TYPE_QUERY nodes.

    */

   void getQueries([optional] out unsigned long queryCount,

                   [retval,array,size_is(queryCount)] out nsINavHistoryQuery queries);

   /**

    * Get the options which group this node's children.

    * Only valid for RESULT_TYPE_QUERY nodes.

    */

   readonly attribute nsINavHistoryQueryOptions queryOptions;

   /**

    * For both simple folder nodes and simple-folder-query nodes, this is set

    * to the concrete itemId of the folder. Otherwise, this is set to -1.

    */

   readonly attribute long long folderItemId;

 };

 /**

  * Allows clients to observe what is happening to a result as it updates itself

  * according to history and bookmark system events. Register this observer on a

  * result using nsINavHistoryResult::addObserver.

  */

 [scriptable, uuid(f62d8b6b-3c4e-4a9f-a897-db605d0b7a0f)]

 interface nsINavHistoryResultObserver : nsISupports

 {

   /**

    * Called when 'aItem' is inserted into 'aParent' at index 'aNewIndex'.

    * The item previously at index (if any) and everything below it will have

    * been shifted down by one. The item may be a container or a leaf.

    */

   void nodeInserted(in nsINavHistoryContainerResultNode aParent,

                     in nsINavHistoryResultNode aNode,

                     in unsigned long aNewIndex);

   /**

    * Called whan 'aItem' is removed from 'aParent' at 'aOldIndex'. The item

    * may be a container or a leaf. This function will be called after the item

    * has been removed from its parent list, but before anything else (including

    * NULLing out the item's parent) has happened.

    */

   void nodeRemoved(in nsINavHistoryContainerResultNode aParent,

                    in nsINavHistoryResultNode aItem,

                    in unsigned long aOldIndex);

   /**

    * Called whan 'aItem' is moved from 'aOldParent' at 'aOldIndex' to

    * aNewParent at aNewIndex. The item may be a container or a leaf.

    *

    * XXX: at the moment, this method is called only when an item is moved

    * within the same container. When an item is moved between containers,

    * a new node is created for the item, and the itemRemoved/itemAdded methods

    * are used.

    */

   void nodeMoved(in nsINavHistoryResultNode aNode,

                  in nsINavHistoryContainerResultNode aOldParent,

                  in unsigned long aOldIndex,

                  in nsINavHistoryContainerResultNode aNewParent,

                  in unsigned long aNewIndex);

   /**

    * Called right after aNode's title has changed.

    * 

    * @param aNode

    *        a result node

    * @param aNewTitle

    *        the new title

    */

   void nodeTitleChanged(in nsINavHistoryResultNode aNode,

                         in AUTF8String aNewTitle);

   /**

    * Called right after aNode's uri property has changed.

    * 

    * @param aNode

    *        a result node

    * @param aNewURI

    *        the new uri

    */

   void nodeURIChanged(in nsINavHistoryResultNode aNode,

                       in AUTF8String aNewURI);

   /**

    * Called right after aNode's icon property has changed.

    *

    * @param aNode

    *        a result node

    *

    * @note: The new icon is accessible through aNode.icon.

    */

   void nodeIconChanged(in nsINavHistoryResultNode aNode);

   /**

    * Called right after aNode's time property or accessCount property, or both,

    * have changed.

    *

    * @param aNode

    *        a uri result node

    * @param aNewVisitDate

    *        the new visit date

    * @param aNewAccessCount

    *        the new access-count

    */

   void nodeHistoryDetailsChanged(in nsINavHistoryResultNode aNode,

                                  in PRTime aNewVisitDate,

                                  in unsigned long aNewAccessCount);

   /**

    * Called when the tags set on the uri represented by aNode have changed.

    *

    * @param aNode

    *        a uri result node

    *

    * @note: The new tags list is accessible through aNode.tags.

    */

   void nodeTagsChanged(in nsINavHistoryResultNode aNode);

   /**

    * Called right after the aNode's keyword property has changed.

    * 

    * @param aNode

    *        a uri result node

    * @param aNewKeyword

    *        the new keyword

    */

   void nodeKeywordChanged(in nsINavHistoryResultNode aNode,

                           in AUTF8String aNewKeyword);

   /**

    * Called right after an annotation of aNode's has changed (set, altered, or

    * unset).

    * 

    * @param aNode

    *        a result node

    * @param aAnnoName

    *        the name of the annotation that changed

    */

   void nodeAnnotationChanged(in nsINavHistoryResultNode aNode,

                              in AUTF8String aAnnoName);

   /**

    * Called right after aNode's dateAdded property has changed.

    *

    * @param aNode

    *        a result node

    * @param aNewValue

    *        the new value of the dateAdded property

    */

   void nodeDateAddedChanged(in nsINavHistoryResultNode aNode,

                             in PRTime aNewValue);

   /**

    * Called right after aNode's dateModified property has changed.

    *

    * @param aNode

    *        a result node

    * @param aNewValue

    *        the new value of the dateModified property

    */

   void nodeLastModifiedChanged(in nsINavHistoryResultNode aNode,

                                in PRTime aNewValue);

   /**

    * Called after a container changes state.

    *

    * @param aContainerNode

    *        The container that has changed state.

    * @param aOldState

    *        The state that aContainerNode has transitioned out of.

    * @param aNewState

    *        The state that aContainerNode has transitioned into.

    */

   void containerStateChanged(in nsINavHistoryContainerResultNode aContainerNode,

                              in unsigned long aOldState,

                              in unsigned long aNewState);

   /**

    * Called when something significant has happened within the container. The

    * contents of the container should be re-built.

    *

    * @param aContainerNode

    *        the container node to invalidate

    */

   void invalidateContainer(in nsINavHistoryContainerResultNode aContainerNode);

   /**

    * This is called to indicate to the UI that the sort has changed to the

    * given mode. For trees, for example, this would update the column headers

    * to reflect the sorting. For many other types of views, this won't be

    * applicable.

    *

    * @param sortingMode  One of nsINavHistoryQueryOptions.SORT_BY_* that

    *                     indicates the new sorting mode.

    *

    * This only is expected to update the sorting UI. invalidateAll() will also

    * get called if the sorting changes to update everything.

    */

   void sortingChanged(in unsigned short sortingMode);

   /**

    * This is called to indicate that a batch operation is about to start or end.

    * The observer could want to disable some events or updates during batches,

    * since multiple operations are packed in a short time.

    * For example treeviews could temporarily suppress select notifications.

    *

    * @param aToggleMode

    *        true if a batch is starting, false if it's ending.

    */

   void batching(in boolean aToggleMode);

   /**

    * Called by the result when this observer is added.

    */

   attribute nsINavHistoryResult result;

 };

 /**

  * TODO: Bug 517719.

  *

  * A predefined view adaptor for interfacing results with an nsITree. This

  * object will remove itself from its associated result when the tree has been

  * detached. This prevents circular references. Users should be aware of this,

  * if you want to re-use the same viewer, you will need to keep your own

  * reference to it and re-initialize it when the tree changes. If you use this

  * object, attach it to a result, never attach it to a tree, and forget about

  * it, it will leak!

  */

 [scriptable, uuid(f8b518c0-1faf-11df-8a39-0800200c9a66)]

 interface nsINavHistoryResultTreeViewer : nsINavHistoryResultObserver

 {

   /**

    * This allows you to get at the real node for a given row index. This is

    * only valid when a tree is attached.

    */

   nsINavHistoryResultNode nodeForTreeIndex(in unsigned long aIndex);

   /**

    * Reverse of nodeForFlatIndex, returns the row index for a given result node.

    * Returns INDEX_INVISIBLE if the item is not visible (for example, its

    * parent is collapsed). This is only valid when a tree is attached. The

    * the result will always be INDEX_INVISIBLE if not.

    * 

    * Note: This sounds sort of obvious, but it got me: aNode must be a node

    *       retrieved from the same result that this viewer is for. If you 

    *       execute another query and get a node from a _different_ result, this 

    *       function will always return the index of that node in the tree that

    *       is attached to that result.

    */

   const unsigned long INDEX_INVISIBLE = 0xffffffff;

   unsigned long treeIndexForNode(in nsINavHistoryResultNode aNode);

 };

 /**

  * The result of a history/bookmark query.

  */

 [scriptable, uuid(c2229ce3-2159-4001-859c-7013c52f7619)]

 interface nsINavHistoryResult : nsISupports

 {

   /**

    * Sorts all nodes recursively by the given parameter, one of

    * nsINavHistoryQueryOptions.SORT_BY_*  This will update the corresponding

    * options for this result, so that re-using the current options/queries will

    * always give you the current view.

    */

   attribute unsigned short sortingMode;

   /**

    * The annotation to use in SORT_BY_ANNOTATION_* sorting modes, set this

    * before setting the sortingMode attribute.

    */

   attribute AUTF8String sortingAnnotation;

   /**

    * Whether or not notifications on result changes are suppressed.

    * Initially set to false.

    *

    * Use this to avoid flickering and to improve performance when you

    * do temporary changes to the result structure (e.g. when searching for a

    * node recursively).

    */

   attribute boolean suppressNotifications;

   /**

    * Adds an observer for changes done in the result.

    *

    * @param aObserver

    *        a result observer.

    * @param aOwnsWeak

    *        If false, the result will keep an owning reference to the observer,

    *        which must be removed using removeObserver.

    *        If true, the result will keep a weak reference to the observer, which

    *        must implement nsISupportsWeakReference.

    *

    * @see nsINavHistoryResultObserver

    */

   void addObserver(in nsINavHistoryResultObserver aObserver, in boolean aOwnsWeak);

   /**

    * Removes an observer that was added by addObserver.

    *

    * @param aObserver

    *        a result observer that was added by addObserver.

    */

   void removeObserver(in nsINavHistoryResultObserver aObserver);

   /**

    * This is the root of the results. Remember that you need to open all

    * containers for their contents to be valid.

    *

    * When a result goes out of scope it will continue to observe changes till

    * it is cycle collected.  While the result waits to be collected it will stay

    * in memory, and continue to update itself, potentially causing unwanted

    * additional work.  When you close the root node the result will stop

    * observing changes, so it is good practice to close the root node when you

    * are done with a result, since that will avoid unwanted performance hits.

    */

   readonly attribute nsINavHistoryContainerResultNode root;

 };

 /**

  * Similar to nsIRDFObserver for history. Note that we don't pass the data

  * source since that is always the global history.

  *

  * DANGER! If you are in the middle of a batch transaction, there may be a

  * database transaction active. You can still access the DB, but be careful.

  */

 [scriptable, uuid(0f0f45b0-13a1-44ae-a0ab-c6046ec6d4da)]

 interface nsINavHistoryObserver : nsISupports

 {

   /**

    * Notifies you that a bunch of things are about to change, don't do any

    * heavy-duty processing until onEndUpdateBatch is called.

    */

   void onBeginUpdateBatch();

   /**

    * Notifies you that we are done doing a bunch of things and you should go

    * ahead and update UI, etc.

    */

   void onEndUpdateBatch();

   /**

    * Called when a resource is visited. This is called the first time a

    * resource (page, image, etc.) is seen as well as every subsequent time.

    *

    * Normally, transition types of TRANSITION_EMBED (corresponding to images in

    * a page, for example) are not displayed in history results (unless

    * includeHidden is set). Many observers can ignore _EMBED notifications

    * (which will comprise the majority of visit notifications) to save work.

    *

    * @param aVisitID        ID of the visit that was just created.

    * @param aTime           Time of the visit

    * @param aSessionID      No longer supported (always set to 0).

    * @param aReferringID    The ID of the visit the user came from. 0 if empty.

    * @param aTransitionType One of nsINavHistory.TRANSITION_*

    * @param aGUID           The unique ID associated with the page.

    * @param aHidden         Whether the visited page is marked as hidden.

    */

   void onVisit(in nsIURI aURI,

                in long long aVisitID,

                in PRTime aTime,

                in long long aSessionID,

                in long long aReferringID,

                in unsigned long aTransitionType,

                in ACString aGUID,

                in boolean aHidden);

   /**

    * Called whenever either the "real" title or the custom title of the page

    * changed. BOTH TITLES ARE ALWAYS INCLUDED in this notification, even though

    * only one will change at a time. Often, consumers will want to display the

    * user title if it is available, and fall back to the page title (the one

    * specified in the <title> tag of the page).

    *

    * Note that there is a difference between an empty title and a NULL title.

    * An empty string means that somebody specifically set the title to be

    * nothing. NULL means nobody set it. From C++: use IsVoid() and SetIsVoid()

    * to see whether an empty string is "null" or not (it will always be an

    * empty string in either case).

    *

    * @param aURI

    *        The URI of the page.

    * @param aPageTitle

    *        The new title of the page.

    * @param aGUID

    *        The unique ID associated with the page.

    */

   void onTitleChanged(in nsIURI aURI,

                       in AString aPageTitle,

                       in ACString aGUID);

   /**

    * Called when an individual page's frecency has changed.

    *

    * This is not called for pages whose frecencies change as the result of some

    * large operation where some large or unknown number of frecencies change at

    * once.  Use onManyFrecenciesChanged to detect such changes.

    *

    * @param aURI

    *        The page's URI.

    * @param aNewFrecency

    *        The page's new frecency.

    * @param aGUID

    *        The page's GUID.

    * @param aHidden

    *        True if the page is marked as hidden.

    * @param aVisitDate

    *        The page's last visit date.

    */

   void onFrecencyChanged(in nsIURI aURI,

                          in long aNewFrecency,

                          in ACString aGUID,

                          in boolean aHidden,

                          in PRTime aVisitDate);

   /**

    * Called when the frecencies of many pages have changed at once.

    *

    * onFrecencyChanged is not called for each of those pages.

    */

   void onManyFrecenciesChanged();

   /**

    * Removed by the user.

    */

   const unsigned short REASON_DELETED = 0;

   /**

    * Removed by automatic expiration.

    */

   const unsigned short REASON_EXPIRED = 1;

   /**

    * This page and all of its visits are being deleted. Note: the page may not

    * necessarily have actually existed for this function to be called.

    *

    * Delete notifications are only 99.99% accurate. Batch delete operations

    * must be done in two steps, so first come notifications, then a bulk

    * delete. If there is some error in the middle (for example, out of memory)

    * then you'll get a notification and it won't get deleted. There's no easy

    * way around this.

    *

    * @param aURI

    *        The URI that was deleted.

    * @param aGUID

    *        The unique ID associated with the page.

    * @param aReason

    *        Indicates the reason for the removal.  see REASON_* constants.

    */

   void onDeleteURI(in nsIURI aURI,

                    in ACString aGUID,

                    in unsigned short aReason);

   /**

    * Notification that all of history is being deleted.

    */

   void onClearHistory();

   /**

    * onPageChanged attribute indicating that favicon has been updated.

    * aNewValue parameter will be set to the new favicon URI string.

    */

   const unsigned long ATTRIBUTE_FAVICON = 3;

   /**

    * An attribute of this page changed.

    *

    * @param aURI

    *        The URI of the page on which an attribute changed.

    * @param aChangedAttribute

    *        The attribute whose value changed.  See ATTRIBUTE_* constants.

    * @param aNewValue

    *        The attribute's new value.

    * @param aGUID

    *        The unique ID associated with the page.

    */

   void onPageChanged(in nsIURI aURI,

                      in unsigned long aChangedAttribute,

                      in AString aNewValue,

                      in ACString aGUID);

   /**

    * Called when some visits of an history entry are expired.

    *

    * @param aURI

    *        The page whose visits have been expired.

    * @param aVisitTime

    *        The largest visit time in microseconds that has been expired.  We

    *        guarantee that we don't have any visit older than this date.

    * @param aGUID

    *        The unique ID associated with the page.

    *

    * @note: when all visits for a page are expired and also the full page entry

    *        is expired, you will only get an onDeleteURI notification.  If a

    *        page entry is removed, then you can be sure that we don't have

    *        anymore visits for it.

    * @param aReason

    *        Indicates the reason for the removal.  see REASON_* constants.

    * @param aTransitionType

    *        If it's a valid TRANSITION_* value, all visits of the specified type

    *        have been removed.

    */

   void onDeleteVisits(in nsIURI aURI,

                       in PRTime aVisitTime,

                       in ACString aGUID,

                       in unsigned short aReason,

                       in unsigned long aTransitionType);

 };

 /**

  * This object encapsulates all the query parameters you're likely to need

  * when building up history UI. All parameters are ANDed together.

  *

  * This is not intended to be a super-general query mechanism. This was designed

  * so that most queries can be done in only one SQL query. This is important

  * because, if the user has their profile on a networked drive, query latency

  * can be non-negligible.

  */

 [scriptable, uuid(dc87ae79-22f1-4dcf-975b-852b01d210cb)]

 interface nsINavHistoryQuery : nsISupports

 {

   /**

    * Time range for results (INCLUSIVE). The *TimeReference is one of the

    * constants TIME_RELATIVE_* which indicates how to interpret the

    * corresponding time value.

    *   TIME_RELATIVE_EPOCH (default):

    *     The time is relative to Jan 1 1970 GMT, (this is a normal PRTime)

    *   TIME_RELATIVE_TODAY:

    *     The time is relative to this morning at midnight. Normally used for

    *     queries relative to today. For example, a "past week" query would be

    *     today-6 days -> today+1 day

    *   TIME_RELATIVE_NOW:

    *     The time is relative to right now.

    *

    * Note: PRTime is in MICROseconds since 1 Jan 1970. Javascript date objects

    * are expressed in MILLIseconds since 1 Jan 1970.

    *

    * As a special case, a 0 time relative to TIME_RELATIVE_EPOCH indicates that

    * the time is not part of the query. This is the default, so an empty query

    * will match any time. The has* functions return whether the corresponding

    * time is considered.

    *

    * You can read absolute*Time to get the time value that the currently loaded

    * reference points + offset resolve to.

    */

   const unsigned long TIME_RELATIVE_EPOCH = 0;

   const unsigned long TIME_RELATIVE_TODAY = 1;

   const unsigned long TIME_RELATIVE_NOW = 2;

   attribute PRTime beginTime;

   attribute unsigned long beginTimeReference;

   readonly attribute boolean hasBeginTime;

   readonly attribute PRTime absoluteBeginTime;

   attribute PRTime endTime;

   attribute unsigned long endTimeReference;

   readonly attribute boolean hasEndTime;

   readonly attribute PRTime absoluteEndTime;

   /**

    * Text search terms.

    */

   attribute AString searchTerms;

   readonly attribute boolean hasSearchTerms;

   /**

    * Set lower or upper limits for how many times an item has been

    * visited.  The default is -1, and in that case all items are

    * matched regardless of their visit count.

    */

   attribute long minVisits;

   attribute long maxVisits;

   /**

    * When the set of transitions is nonempty, results are limited to pages which

    * have at least one visit for each of the transition types.

    * @note: For searching on more than one transition this can be very slow.

    *

    * Limit results to the specified list of transition types.

    */

   void setTransitions([const,array, size_is(count)] in unsigned long transitions,

                       in unsigned long count);

   /**

    * Get the transitions set for this query.

    */

   void getTransitions([optional] out unsigned long count,

                       [retval,array,size_is(count)] out unsigned long transitions);

   /**

    * Get the count of the set query transitions.

    */

   readonly attribute unsigned long transitionCount;

   /**

    * When set, returns only bookmarked items, when unset, returns anything. Setting this

    * is equivalent to listing all bookmark folders in the 'folders' parameter.

    */

   attribute boolean onlyBookmarked;

   /**

    * This controls the meaning of 'domain', and whether it is an exact match

    * 'domainIsHost' = true, or hierarchical (= false).

    */

   attribute boolean domainIsHost;

   /**

    * This is the host or domain name (controlled by domainIsHost). When

    * domainIsHost, domain only does exact matching on host names. Otherwise,

    * it will return anything whose host name ends in 'domain'.

    *

    * This one is a little different than most. Setting it to an empty string

    * is a real query and will match any URI that has no host name (local files

    * and such). Set this to NULL (in C++ use SetIsVoid) if you don't want

    * domain matching.

    */

   attribute AUTF8String domain;

   readonly attribute boolean hasDomain;

   /**

    * Controls the interpretation of 'uri'. When unset (default), the URI will

    * request an exact match of the specified URI. When set, any history entry

    * beginning in 'uri' will match. For example "http://bar.com/foo" will match

    * "http://bar.com/foo" as well as "http://bar.com/foo/baz.gif".

    */

   attribute boolean uriIsPrefix;

   /**

    * This is a URI to match, to, for example, find out every time you visited

    * a given URI. Use uriIsPrefix to control whether this is an exact match.

    */

   attribute nsIURI uri;

   readonly attribute boolean hasUri;

   /**

    * Test for existence or non-existence of a given annotation. We don't

    * currently support >1 annotation name per query. If 'annotationIsNot' is

    * true, we test for the non-existence of the specified annotation.

    *

    * Testing for not annotation will do the same thing as a normal query and

    * remove everything that doesn't have that annotation. Asking for things

    * that DO have a given annotation is a little different. It also includes

    * things that have never been visited. This allows place queries to be

    * returned as well as anything else that may have been tagged with an

    * annotation. This will only work for RESULTS_AS_URI since there will be

    * no visits for these items.

    */

   attribute boolean annotationIsNot;

   attribute AUTF8String annotation;

   readonly attribute boolean hasAnnotation;

   /**

    * Limit results to items that are tagged with all of the given tags.  This

    * attribute must be set to an array of strings.  When called as a getter it

    * will return an array of strings sorted ascending in lexicographical order.

    * The array may be empty in either case.  Duplicate tags may be specified

    * when setting the attribute, but the getter returns only unique tags.

    *

    * To search for items that are tagged with any given tags rather than all,

    * multiple queries may be passed to nsINavHistoryService.executeQueries().

    */

   attribute nsIVariant tags;

   /**

    * If 'tagsAreNot' is true, the results are instead limited to items that

    * are not tagged with any of the given tags.  This attribute is used in

    * conjunction with the 'tags' attribute.

    */

   attribute boolean tagsAreNot;

   /**

    * Limit results to items that are in all of the given folders.

    */

   void getFolders([optional] out unsigned long count,

                   [retval,array,size_is(count)] out long long folders);

   readonly attribute unsigned long folderCount;

   /**

    * For the special result type RESULTS_AS_TAG_CONTENTS we can define only

    * one folder that must be a tag folder. This is not recursive so results

    * will be returned from the first level of that folder.

    */

   void setFolders([const,array, size_is(folderCount)] in long long folders,

                   in unsigned long folderCount);

   /**

    * Creates a new query item with the same parameters of this one.

    */

   nsINavHistoryQuery clone();

 };

 /**

  * This object represents the global options for executing a query.

  */

 [scriptable, uuid(8198dfa7-8061-4766-95cb-fa86b3c00a47)]

 interface nsINavHistoryQueryOptions : nsISupports

 {

   /**

    * You can ask for the results to be pre-sorted. Since the DB has indices

    * of many items, it can produce sorted results almost for free. These should

    * be self-explanatory.

    *

    * Note: re-sorting is slower, as is sorting by title or when you have a

    * host name.

    *

    * For bookmark items, SORT_BY_NONE means sort by the natural bookmark order.

    */

   const unsigned short SORT_BY_NONE = 0;

   const unsigned short SORT_BY_TITLE_ASCENDING = 1;

   const unsigned short SORT_BY_TITLE_DESCENDING = 2;

   const unsigned short SORT_BY_DATE_ASCENDING = 3;

   const unsigned short SORT_BY_DATE_DESCENDING = 4;

   const unsigned short SORT_BY_URI_ASCENDING = 5;

   const unsigned short SORT_BY_URI_DESCENDING = 6;

   const unsigned short SORT_BY_VISITCOUNT_ASCENDING = 7;

   const unsigned short SORT_BY_VISITCOUNT_DESCENDING = 8;

   const unsigned short SORT_BY_KEYWORD_ASCENDING = 9;

   const unsigned short SORT_BY_KEYWORD_DESCENDING = 10;

   const unsigned short SORT_BY_DATEADDED_ASCENDING = 11;

   const unsigned short SORT_BY_DATEADDED_DESCENDING = 12;

   const unsigned short SORT_BY_LASTMODIFIED_ASCENDING = 13;

   const unsigned short SORT_BY_LASTMODIFIED_DESCENDING = 14;

   const unsigned short SORT_BY_TAGS_ASCENDING = 17;

   const unsigned short SORT_BY_TAGS_DESCENDING = 18;

   const unsigned short SORT_BY_ANNOTATION_ASCENDING = 19;

   const unsigned short SORT_BY_ANNOTATION_DESCENDING = 20;

   const unsigned short SORT_BY_FRECENCY_ASCENDING = 21;

   const unsigned short SORT_BY_FRECENCY_DESCENDING = 22;

   /**

    * "URI" results, one for each URI visited in the range. Individual result

    * nodes will be of type "URI".

    */

   const unsigned short RESULTS_AS_URI = 0;

   /**

    * "Visit" results, with one for each time a page was visited (this will

    * often give you multiple results for one URI). Individual result nodes will

    * have type "Visit"

    *

    * @note This result type is only supported by QUERY_TYPE_HISTORY.

    */

   const unsigned short RESULTS_AS_VISIT = 1;

   /**

    * This is identical to RESULT_TYPE_VISIT except that individual result nodes

    * will have type "FullVisit".  This is used for the attributes that are not

    * commonly accessed to save space in the common case (the lists can be very

    * long).

    *

    * @note Not yet implemented. See bug 409662.

    * @note This result type is only supported by QUERY_TYPE_HISTORY.

    */

   const unsigned short RESULTS_AS_FULL_VISIT = 2;

   /**

    * This returns query nodes for each predefined date range where we 

    * had visits. The node contains information how to load its content:

    * - visits for the given date range will be loaded.

    *

    * @note This result type is only supported by QUERY_TYPE_HISTORY.

    */

   const unsigned short RESULTS_AS_DATE_QUERY = 3;

   /**

    * This returns nsINavHistoryQueryResultNode nodes for each site where we 

    * have visits. The node contains information how to load its content:

    * - last visit for each url in the given host will be loaded.

    *

    * @note This result type is only supported by QUERY_TYPE_HISTORY.

    */

   const unsigned short RESULTS_AS_SITE_QUERY = 4;

   /**

    * This returns nsINavHistoryQueryResultNode nodes for each day where we 

    * have visits. The node contains information how to load its content:

    * - list of hosts visited in the given period will be loaded.

    *

    * @note This result type is only supported by QUERY_TYPE_HISTORY.

    */

   const unsigned short RESULTS_AS_DATE_SITE_QUERY = 5;

   /**

    * This returns nsINavHistoryQueryResultNode nodes for each tag.

    * The node contains information how to load its content:

    * - list of bookmarks with the given tag will be loaded.

    *

    * @note Setting this resultType will force queryType to QUERY_TYPE_BOOKMARKS.

    */

   const unsigned short RESULTS_AS_TAG_QUERY = 6;

   /**

    * This is a container with an URI result type that contains the last

    * modified bookmarks for the given tag.

    * Tag folder id must be defined in the query.

    *

    * @note Setting this resultType will force queryType to QUERY_TYPE_BOOKMARKS.

    */

   const unsigned short RESULTS_AS_TAG_CONTENTS = 7;

   /**

    * The sorting mode to be used for this query.

    * mode is one of SORT_BY_*

    */

   attribute unsigned short sortingMode;

   /**

    * The annotation to use in SORT_BY_ANNOTATION_* sorting modes.

    */

   attribute AUTF8String sortingAnnotation;

   /**

    * Sets the result type. One of RESULT_TYPE_* which includes how URIs are

    * represented.

    */

   attribute unsigned short resultType;

   /**

    * This option excludes all URIs and separators from a bookmarks query.

    * This would be used if you just wanted a list of bookmark folders and

    * queries (such as the left pane of the places page).

    * Defaults to false.

    */

   attribute boolean excludeItems;

   /**

    * Set to true to exclude queries ("place:" URIs) from the query results.

    * Simple folder queries (bookmark folder symlinks) will still be included.

    * Defaults to false.

    */

   attribute boolean excludeQueries;

   /**

    * Set to true to exclude read-only folders from the query results. This is

    * designed for cases where you want to give the user the option of filing

    * something into a list of folders. It only affects cases where the actual

    * folder result node would appear in its parent folder and filters it out.

    * It doesn't affect the query at all, and doesn't affect more complex

    * queries (such as "folders with annotation X").

    */

   attribute boolean excludeReadOnlyFolders;

   /**

    * When set, allows items with "place:" URIs to appear as containers,

    * with the container's contents filled in from the stored query.

    * If not set, these will appear as normal items. Doesn't do anything if

    * excludeQueries is set. Defaults to false.

    *

    * Note that this has no effect on folder links, which are place: URIs

    * returned by nsINavBookmarkService.GetFolderURI. These are always expanded

    * and will appear as bookmark folders.

    */

   attribute boolean expandQueries;

   /**

    * Some pages in history are marked "hidden" and thus don't appear by default

    * in queries.  These include automatic framed visits and redirects.  Setting

    * this attribute will return all pages, even hidden ones.  Does nothing for

    * bookmark queries. Defaults to false.

    */

   attribute boolean includeHidden;

   /**

    * This is the maximum number of results that you want. The query is exeucted,

    * the results are sorted, and then the top 'maxResults' results are taken

    * and returned. Set to 0 (the default) to get all results.

    *

    * THIS DOES NOT WORK IN CONJUNCTION WITH SORTING BY TITLE. This is because

    * sorting by title requires us to sort after using locale-sensetive sorting

    * (as opposed to letting the database do it for us).

    *

    * Instead, we get the result ordered by date, pick the maxResult most recent

    * ones, and THEN sort by title.

    */

   attribute unsigned long maxResults;

   const unsigned short QUERY_TYPE_HISTORY = 0;

   const unsigned short QUERY_TYPE_BOOKMARKS = 1;

   /* Unified queries are not yet implemented. See bug 378798 */

   const unsigned short QUERY_TYPE_UNIFIED = 2;

   /**

    * The type of search to use when querying the DB; This attribute is only

    * honored by query nodes. It is silently ignored for simple folder queries.

    */

   attribute unsigned short queryType;

   /**

    * When this is true, the root container node generated by these options and

    * its descendant containers will be opened asynchronously if they support it.

    * This is false by default.

    *

    * @note Currently only bookmark folder containers support being opened

    *       asynchronously.

    */

   attribute boolean asyncEnabled;

   /**

    * Creates a new options item with the same parameters of this one.

    */

   nsINavHistoryQueryOptions clone();

 };

 [scriptable, uuid(baebc597-9daf-4103-a325-e41ef9e7608a)]

 interface nsINavHistoryService : nsISupports

 {

   /**

    * System Notifications:

    *

    * places-init-complete - Sent once the History service is completely

    *                        initialized successfully.

    * places-database-locked - Sent if initialization of the History service

    *                          failed due to the inability to open the places.sqlite

    *                          for access reasons.

    */

   /**

    * This transition type means the user followed a link and got a new toplevel

    * window.

    */

   const unsigned long TRANSITION_LINK = 1;

   /**

    * This transition type means that the user typed the page's URL in the

    * URL bar or selected it from URL bar autocomplete results, clicked on

    * it from a history query (from the History sidebar, History menu, 

    * or history query in the personal toolbar or Places organizer.

    */

   const unsigned long TRANSITION_TYPED = 2;

   /**

    * This transition is set when the user followed a bookmark to get to the

    * page.

    */

   const unsigned long TRANSITION_BOOKMARK = 3;

   /**

    * This transition type is set when some inner content is loaded. This is

    * true of all images on a page, and the contents of the iframe. It is also

    * true of any content in a frame if the user did not explicitly follow

    * a link to get there.

    */

   const unsigned long TRANSITION_EMBED = 4;

   /**

    * Set when the transition was a permanent redirect.

    */

   const unsigned long TRANSITION_REDIRECT_PERMANENT = 5;

   /**

    * Set when the transition was a temporary redirect.

    */

   const unsigned long TRANSITION_REDIRECT_TEMPORARY = 6;

   /**

    * Set when the transition is a download.

    */

   const unsigned long TRANSITION_DOWNLOAD = 7;

   /**

    * This transition type means the user followed a link and got a visit in

    * a frame.

    */

   const unsigned long TRANSITION_FRAMED_LINK = 8;

   /**

    * Set when database is coherent

    */

   const unsigned short DATABASE_STATUS_OK = 0;

   /**

    * Set when database did not exist and we created a new one

    */

   const unsigned short DATABASE_STATUS_CREATE = 1;

   /**

    * Set when database was corrupt and we replaced it

    */

   const unsigned short DATABASE_STATUS_CORRUPT = 2;

   /**

    * Set when database schema has been upgraded

    */

   const unsigned short DATABASE_STATUS_UPGRADED = 3;

   /**

    * Returns the current database status

    */

   readonly attribute unsigned short databaseStatus;

   /**

    * True if there is any history. This can be used in UI to determine whether

    * the "clear history" button should be enabled or not. This is much better

    * than using BrowserHistory.count since that can be very slow if there is

    * a lot of history (it must enumerate each item). This is pretty fast.

    */

   readonly attribute boolean hasHistoryEntries;

   /**

    * Gets the original title of the page.

    * @deprecated use mozIAsyncHistory.getPlacesInfo instead.

    */

   AString getPageTitle(in nsIURI aURI);

   /**

    * This is just like markPageAsTyped (in nsIBrowserHistory, also implemented

    * by the history service), but for bookmarks. It declares that the given URI

    * is being opened as a result of following a bookmark. If this URI is loaded

    * soon after this message has been received, that transition will be marked

    * as following a bookmark.

    */

   void markPageAsFollowedBookmark(in nsIURI aURI);

   /**

    * Designates the url as having been explicitly typed in by the user.

    *

    * @param aURI

    *        URI of the page to be marked.

    */

   void markPageAsTyped(in nsIURI aURI);

   /**

    * Designates the url as coming from a link explicitly followed by

    * the user (for example by clicking on it).

    *

    * @param aURI

    *        URI of the page to be marked.

    */

   void markPageAsFollowedLink(in nsIURI aURI);

   /**

    * Gets the stored character-set for an URI.

    *

    * @param aURI

    *        URI to retrieve character-set for

    * @return character-set, empty string if not found

    */

   AString getCharsetForURI(in nsIURI aURI);

   /**

    * Sets the character-set for an URI.

    *

    * @param aURI

    *        URI to set the character-set for

    * @param aCharset

    *        character-set to be set

    */

   void setCharsetForURI(in nsIURI aURI, in AString aCharset);

   /**

    * Returns true if this URI would be added to the history. You don't have to

    * worry about calling this, adding a visit will always check before

    * actually adding the page. This function is public because some components

    * may want to check if this page would go in the history (i.e. for

    * annotations).

    */

   boolean canAddURI(in nsIURI aURI);

   /**

    * This returns a new query object that you can pass to executeQuer[y/ies].

    * It will be initialized to all empty (so using it will give you all history).

    */

   nsINavHistoryQuery getNewQuery();

   /**

    * This returns a new options object that you can pass to executeQuer[y/ies]

    * after setting the desired options.

    */

   nsINavHistoryQueryOptions getNewQueryOptions();

   /**

    * Executes a single query.

    */

   nsINavHistoryResult executeQuery(in nsINavHistoryQuery aQuery,

                                    in nsINavHistoryQueryOptions options);

   /**

    * Executes an array of queries. All of the query objects are ORed

    * together. Within a query, all the terms are ANDed together as in

    * executeQuery. See executeQuery()

    */

   nsINavHistoryResult executeQueries(

     [array,size_is(aQueryCount)] in nsINavHistoryQuery aQueries,

     in unsigned long aQueryCount,

     in nsINavHistoryQueryOptions options);

   /**

    * Converts a query URI-like string to an array of actual query objects for

    * use to executeQueries(). The output query array may be empty if there is

    * no information. However, there will always be an options structure returned

    * (if nothing is defined, it will just have the default values).

    */

   void queryStringToQueries(in AUTF8String aQueryString,

     [array, size_is(aResultCount)] out nsINavHistoryQuery aQueries,

     out unsigned long aResultCount,

     out nsINavHistoryQueryOptions options);

   /**

    * Converts a query into an equivalent string that can be persisted. Inverse

    * of queryStringToQueries()

    */

   AUTF8String queriesToQueryString(

     [array, size_is(aQueryCount)] in nsINavHistoryQuery aQueries,

     in unsigned long aQueryCount,

     in nsINavHistoryQueryOptions options);

   /**

    * Adds a history observer. If ownsWeak is false, the history service will

    * keep an owning reference to the observer.  If ownsWeak is true, then

    * aObserver must implement nsISupportsWeakReference, and the history service

    * will keep a weak reference to the observer.

    */

   void addObserver(in nsINavHistoryObserver observer, in boolean ownsWeak);

   /**

    * Removes a history observer.

    */

   void removeObserver(in nsINavHistoryObserver observer);

   /**

    * Runs the passed callback in batch mode. Use this when a lot of things

    * are about to change. Calls can be nested, observers will only be

    * notified when all batches begin/end.

    *

    * @param aCallback

    *        nsINavHistoryBatchCallback interface to call.

    * @param aUserData

    *        Opaque parameter passed to nsINavBookmarksBatchCallback

    */

   void runInBatchMode(in nsINavHistoryBatchCallback aCallback,

                       in nsISupports aClosure);

   /** 

    * True if history is disabled. currently, 

    * history is disabled if the places.history.enabled pref is false.

    */

   readonly attribute boolean historyDisabled;

 };

 /**

  * @see runInBatchMode of nsINavHistoryService/nsINavBookmarksService

  */

 [scriptable, uuid(5143f2bb-be0a-4faf-9acb-b0ed3f82952c)]

 interface nsINavHistoryBatchCallback : nsISupports {

   void runBatched(in nsISupports aUserData);

 };