michael@0: /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: /** michael@0: * Using Places services after quit-application is not reliable, so make michael@0: * sure to do any shutdown work on quit-application, or history michael@0: * synchronization could fail, losing latest changes. michael@0: */ michael@0: michael@0: #include "nsISupports.idl" michael@0: michael@0: interface nsIArray; michael@0: interface nsIURI; michael@0: interface nsIVariant; michael@0: interface nsIFile; michael@0: michael@0: interface nsINavHistoryContainerResultNode; michael@0: interface nsINavHistoryQueryResultNode; michael@0: interface nsINavHistoryQuery; michael@0: interface nsINavHistoryQueryOptions; michael@0: interface nsINavHistoryResult; michael@0: interface nsINavHistoryBatchCallback; michael@0: michael@0: [scriptable, uuid(91d104bb-17ef-404b-9f9a-d9ed8de6824c)] michael@0: interface nsINavHistoryResultNode : nsISupports michael@0: { michael@0: /** michael@0: * Indentifies the parent result node in the result set. This is null for michael@0: * top level nodes. michael@0: */ michael@0: readonly attribute nsINavHistoryContainerResultNode parent; michael@0: michael@0: /** michael@0: * The history-result to which this node belongs. michael@0: */ michael@0: readonly attribute nsINavHistoryResult parentResult; michael@0: michael@0: /** michael@0: * URI of the resource in question. For visits and URLs, this is the URL of michael@0: * the page. For folders and queries, this is the place: URI of the michael@0: * corresponding folder or query. This may be empty for other types of michael@0: * objects like host containers. michael@0: */ michael@0: readonly attribute AUTF8String uri; michael@0: michael@0: /** michael@0: * Identifies the type of this node. This node can then be QI-ed to the michael@0: * corresponding specialized result node interface. michael@0: */ michael@0: const unsigned long RESULT_TYPE_URI = 0; // nsINavHistoryResultNode michael@0: michael@0: // Visit nodes are deprecated and unsupported. michael@0: // This line exists just to avoid reusing the value: michael@0: // const unsigned long RESULT_TYPE_VISIT = 1; michael@0: michael@0: // Full visit nodes are deprecated and unsupported. michael@0: // This line exists just to avoid reusing the value: michael@0: // const unsigned long RESULT_TYPE_FULL_VISIT = 2; michael@0: michael@0: // Dynamic containers are deprecated and unsupported. michael@0: // This const exists just to avoid reusing the value: michael@0: // const unsigned long RESULT_TYPE_DYNAMIC_CONTAINER = 4; // nsINavHistoryContainerResultNode michael@0: michael@0: const unsigned long RESULT_TYPE_QUERY = 5; // nsINavHistoryQueryResultNode michael@0: const unsigned long RESULT_TYPE_FOLDER = 6; // nsINavHistoryQueryResultNode michael@0: const unsigned long RESULT_TYPE_SEPARATOR = 7; // nsINavHistoryResultNode michael@0: const unsigned long RESULT_TYPE_FOLDER_SHORTCUT = 9; // nsINavHistoryQueryResultNode michael@0: readonly attribute unsigned long type; michael@0: michael@0: /** michael@0: * Title of the web page, or of the node's query (day, host, folder, etc) michael@0: */ michael@0: readonly attribute AUTF8String title; michael@0: michael@0: /** michael@0: * Total number of times the URI has ever been accessed. For hosts, this michael@0: * is the total of the children under it, NOT the total times the host has michael@0: * been accessed (this would require an additional query, so is not given michael@0: * by default when most of the time it is never needed). michael@0: */ michael@0: readonly attribute unsigned long accessCount; michael@0: michael@0: /** michael@0: * This is the time the user accessed the page. michael@0: * michael@0: * If this is a visit, it is the exact time that the page visit occurred. michael@0: * michael@0: * If this is a URI, it is the most recent time that the URI was visited. michael@0: * Even if you ask for all URIs for a given date range long ago, this might michael@0: * contain today's date if the URI was visited today. michael@0: * michael@0: * For hosts, or other node types with children, this is the most recent michael@0: * access time for any of the children. michael@0: * michael@0: * For days queries this is the respective endTime - a maximum possible michael@0: * visit time to fit in the day range. michael@0: */ michael@0: readonly attribute PRTime time; michael@0: michael@0: /** michael@0: * This URI can be used as an image source URI and will give you the favicon michael@0: * for the page. It is *not* the URI of the favicon, but rather something michael@0: * that will resolve to the actual image. michael@0: * michael@0: * In most cases, this is an annotation URI that will query the favicon michael@0: * service. If the entry has no favicon, this is the chrome URI of the michael@0: * default favicon. If the favicon originally lived in chrome, this will michael@0: * be the original chrome URI of the icon. michael@0: */ michael@0: readonly attribute AUTF8String icon; michael@0: michael@0: /** michael@0: * This is the number of levels between this node and the top of the michael@0: * hierarchy. The members of result.children have indentLevel = 0, their michael@0: * children have indentLevel = 1, etc. The indent level of the root node is michael@0: * set to -1. michael@0: */ michael@0: readonly attribute long indentLevel; michael@0: michael@0: /** michael@0: * When this item is in a bookmark folder (parent is of type folder), this is michael@0: * the index into that folder of this node. These indices start at 0 and michael@0: * increase in the order that they appear in the bookmark folder. For items michael@0: * that are not in a bookmark folder, this value is -1. michael@0: */ michael@0: readonly attribute long bookmarkIndex; michael@0: michael@0: /** michael@0: * If the node is an item (bookmark, folder or a separator) this value is the michael@0: * row ID of that bookmark in the database. For other nodes, this value is michael@0: * set to -1. michael@0: */ michael@0: readonly attribute long long itemId; michael@0: michael@0: /** michael@0: * If the node is an item (bookmark, folder or a separator) this value is the michael@0: * time that the item was created. For other nodes, this value is 0. michael@0: */ michael@0: readonly attribute PRTime dateAdded; michael@0: michael@0: /** michael@0: * If the node is an item (bookmark, folder or a separator) this value is the michael@0: * time that the item was last modified. For other nodes, this value is 0. michael@0: * michael@0: * @note When an item is added lastModified is set to the same value as michael@0: * dateAdded. michael@0: */ michael@0: readonly attribute PRTime lastModified; michael@0: michael@0: /** michael@0: * For uri nodes, this is a sorted list of the tags, delimited with commans, michael@0: * for the uri represented by this node. Otherwise this is an empty string. michael@0: */ michael@0: readonly attribute AString tags; michael@0: michael@0: /** michael@0: * The unique ID associated with the page. It my return an empty string michael@0: * if the result node is a non-URI node. michael@0: */ michael@0: readonly attribute ACString pageGuid; michael@0: michael@0: /** michael@0: * The unique ID associated with the bookmark. It returns an empty string michael@0: * if the result node is not associated with a bookmark, a folder or a michael@0: * separator. michael@0: */ michael@0: readonly attribute ACString bookmarkGuid; michael@0: }; michael@0: michael@0: michael@0: /** michael@0: * Base class for container results. This includes all types of groupings. michael@0: * Bookmark folders and places queries will be QueryResultNodes which extends michael@0: * these items. michael@0: */ michael@0: [scriptable, uuid(5bac9734-c0ff-44eb-8d19-da88462ff6da)] michael@0: interface nsINavHistoryContainerResultNode : nsINavHistoryResultNode michael@0: { michael@0: michael@0: /** michael@0: * Set this to allow descent into the container. When closed, attempting michael@0: * to call getChildren or childCount will result in an error. You should michael@0: * set this to false when you are done reading. michael@0: * michael@0: * For HOST and DAY groupings, doing this is free since the children have michael@0: * been precomputed. For queries and bookmark folders, being open means they michael@0: * will keep themselves up-to-date by listening for updates and re-querying michael@0: * as needed. michael@0: */ michael@0: attribute boolean containerOpen; michael@0: michael@0: /** michael@0: * Indicates whether the container is closed, loading, or opened. Loading michael@0: * implies that the container has been opened asynchronously and has not yet michael@0: * fully opened. michael@0: */ michael@0: readonly attribute unsigned short state; michael@0: const unsigned short STATE_CLOSED = 0; michael@0: const unsigned short STATE_LOADING = 1; michael@0: const unsigned short STATE_OPENED = 2; michael@0: michael@0: /** michael@0: * This indicates whether this node "may" have children, and can be used michael@0: * when the container is open or closed. When the container is closed, it michael@0: * will give you an exact answer if the node can easily be populated (for michael@0: * example, a bookmark folder). If not (for example, a complex history query), michael@0: * it will return true. When the container is open, it will always be michael@0: * accurate. It is intended to be used to see if we should draw the "+" next michael@0: * to a tree item. michael@0: */ michael@0: readonly attribute boolean hasChildren; michael@0: michael@0: /** michael@0: * This gives you the children of the nodes. It is preferrable to use this michael@0: * interface over the array one, since it avoids creating an nsIArray object michael@0: * and the interface is already the correct type. michael@0: * michael@0: * @throws NS_ERROR_NOT_AVAILABLE if containerOpen is false. michael@0: */ michael@0: readonly attribute unsigned long childCount; michael@0: nsINavHistoryResultNode getChild(in unsigned long aIndex); michael@0: michael@0: /** michael@0: * Get the index of a direct child in this container. michael@0: * michael@0: * @param aNode michael@0: * a result node. michael@0: * michael@0: * @return aNode's index in this container. michael@0: * @throws NS_ERROR_NOT_AVAILABLE if containerOpen is false. michael@0: * @throws NS_ERROR_INVALID_ARG if aNode isn't a direct child of this michael@0: * container. michael@0: */ michael@0: unsigned long getChildIndex(in nsINavHistoryResultNode aNode); michael@0: michael@0: /** michael@0: * Look for a node in the container by some of its details. Does not search michael@0: * closed containers. michael@0: * michael@0: * @param aURI michael@0: * the node's uri attribute value michael@0: * @param aTime michael@0: * the node's time attribute value. michael@0: * @param aItemId michael@0: * the node's itemId attribute value. michael@0: * @param aRecursive michael@0: * whether or not to search recursively. michael@0: * michael@0: * @throws NS_ERROR_NOT_AVAILABLE if this container is closed. michael@0: * @return a result node that matches the given details if any, null michael@0: * otherwise. michael@0: */ michael@0: nsINavHistoryResultNode findNodeByDetails(in AUTF8String aURIString, michael@0: in PRTime aTime, michael@0: in long long aItemId, michael@0: in boolean aRecursive); michael@0: michael@0: /** michael@0: * Returns false if this node's list of children can be modified michael@0: * (adding or removing children, or reordering children), or true if michael@0: * the UI should not allow the list of children to be modified. michael@0: * This is false for bookmark folder nodes unless setFolderReadOnly() has michael@0: * been called to override it, and true for non-folder nodes. michael@0: */ michael@0: readonly attribute boolean childrenReadOnly; michael@0: }; michael@0: michael@0: michael@0: /** michael@0: * Used for places queries and as a base for bookmark folders. michael@0: * michael@0: * Note that if you request places to *not* be expanded in the options that michael@0: * generated this node, this item will report it has no children and never try michael@0: * to populate itself. michael@0: */ michael@0: [scriptable, uuid(a4144c3e-8125-46d5-a719-831bec8095f4)] michael@0: interface nsINavHistoryQueryResultNode : nsINavHistoryContainerResultNode michael@0: { michael@0: /** michael@0: * Get the queries which build this node's children. michael@0: * Only valid for RESULT_TYPE_QUERY nodes. michael@0: */ michael@0: void getQueries([optional] out unsigned long queryCount, michael@0: [retval,array,size_is(queryCount)] out nsINavHistoryQuery queries); michael@0: michael@0: /** michael@0: * Get the options which group this node's children. michael@0: * Only valid for RESULT_TYPE_QUERY nodes. michael@0: */ michael@0: readonly attribute nsINavHistoryQueryOptions queryOptions; michael@0: michael@0: /** michael@0: * For both simple folder nodes and simple-folder-query nodes, this is set michael@0: * to the concrete itemId of the folder. Otherwise, this is set to -1. michael@0: */ michael@0: readonly attribute long long folderItemId; michael@0: }; michael@0: michael@0: michael@0: /** michael@0: * Allows clients to observe what is happening to a result as it updates itself michael@0: * according to history and bookmark system events. Register this observer on a michael@0: * result using nsINavHistoryResult::addObserver. michael@0: */ michael@0: [scriptable, uuid(f62d8b6b-3c4e-4a9f-a897-db605d0b7a0f)] michael@0: interface nsINavHistoryResultObserver : nsISupports michael@0: { michael@0: /** michael@0: * Called when 'aItem' is inserted into 'aParent' at index 'aNewIndex'. michael@0: * The item previously at index (if any) and everything below it will have michael@0: * been shifted down by one. The item may be a container or a leaf. michael@0: */ michael@0: void nodeInserted(in nsINavHistoryContainerResultNode aParent, michael@0: in nsINavHistoryResultNode aNode, michael@0: in unsigned long aNewIndex); michael@0: michael@0: /** michael@0: * Called whan 'aItem' is removed from 'aParent' at 'aOldIndex'. The item michael@0: * may be a container or a leaf. This function will be called after the item michael@0: * has been removed from its parent list, but before anything else (including michael@0: * NULLing out the item's parent) has happened. michael@0: */ michael@0: void nodeRemoved(in nsINavHistoryContainerResultNode aParent, michael@0: in nsINavHistoryResultNode aItem, michael@0: in unsigned long aOldIndex); michael@0: michael@0: /** michael@0: * Called whan 'aItem' is moved from 'aOldParent' at 'aOldIndex' to michael@0: * aNewParent at aNewIndex. The item may be a container or a leaf. michael@0: * michael@0: * XXX: at the moment, this method is called only when an item is moved michael@0: * within the same container. When an item is moved between containers, michael@0: * a new node is created for the item, and the itemRemoved/itemAdded methods michael@0: * are used. michael@0: */ michael@0: void nodeMoved(in nsINavHistoryResultNode aNode, michael@0: in nsINavHistoryContainerResultNode aOldParent, michael@0: in unsigned long aOldIndex, michael@0: in nsINavHistoryContainerResultNode aNewParent, michael@0: in unsigned long aNewIndex); michael@0: michael@0: /** michael@0: * Called right after aNode's title has changed. michael@0: * michael@0: * @param aNode michael@0: * a result node michael@0: * @param aNewTitle michael@0: * the new title michael@0: */ michael@0: void nodeTitleChanged(in nsINavHistoryResultNode aNode, michael@0: in AUTF8String aNewTitle); michael@0: michael@0: /** michael@0: * Called right after aNode's uri property has changed. michael@0: * michael@0: * @param aNode michael@0: * a result node michael@0: * @param aNewURI michael@0: * the new uri michael@0: */ michael@0: void nodeURIChanged(in nsINavHistoryResultNode aNode, michael@0: in AUTF8String aNewURI); michael@0: michael@0: /** michael@0: * Called right after aNode's icon property has changed. michael@0: * michael@0: * @param aNode michael@0: * a result node michael@0: * michael@0: * @note: The new icon is accessible through aNode.icon. michael@0: */ michael@0: void nodeIconChanged(in nsINavHistoryResultNode aNode); michael@0: michael@0: /** michael@0: * Called right after aNode's time property or accessCount property, or both, michael@0: * have changed. michael@0: * michael@0: * @param aNode michael@0: * a uri result node michael@0: * @param aNewVisitDate michael@0: * the new visit date michael@0: * @param aNewAccessCount michael@0: * the new access-count michael@0: */ michael@0: void nodeHistoryDetailsChanged(in nsINavHistoryResultNode aNode, michael@0: in PRTime aNewVisitDate, michael@0: in unsigned long aNewAccessCount); michael@0: michael@0: /** michael@0: * Called when the tags set on the uri represented by aNode have changed. michael@0: * michael@0: * @param aNode michael@0: * a uri result node michael@0: * michael@0: * @note: The new tags list is accessible through aNode.tags. michael@0: */ michael@0: void nodeTagsChanged(in nsINavHistoryResultNode aNode); michael@0: michael@0: /** michael@0: * Called right after the aNode's keyword property has changed. michael@0: * michael@0: * @param aNode michael@0: * a uri result node michael@0: * @param aNewKeyword michael@0: * the new keyword michael@0: */ michael@0: void nodeKeywordChanged(in nsINavHistoryResultNode aNode, michael@0: in AUTF8String aNewKeyword); michael@0: michael@0: /** michael@0: * Called right after an annotation of aNode's has changed (set, altered, or michael@0: * unset). michael@0: * michael@0: * @param aNode michael@0: * a result node michael@0: * @param aAnnoName michael@0: * the name of the annotation that changed michael@0: */ michael@0: void nodeAnnotationChanged(in nsINavHistoryResultNode aNode, michael@0: in AUTF8String aAnnoName); michael@0: michael@0: /** michael@0: * Called right after aNode's dateAdded property has changed. michael@0: * michael@0: * @param aNode michael@0: * a result node michael@0: * @param aNewValue michael@0: * the new value of the dateAdded property michael@0: */ michael@0: void nodeDateAddedChanged(in nsINavHistoryResultNode aNode, michael@0: in PRTime aNewValue); michael@0: michael@0: /** michael@0: * Called right after aNode's dateModified property has changed. michael@0: * michael@0: * @param aNode michael@0: * a result node michael@0: * @param aNewValue michael@0: * the new value of the dateModified property michael@0: */ michael@0: void nodeLastModifiedChanged(in nsINavHistoryResultNode aNode, michael@0: in PRTime aNewValue); michael@0: michael@0: /** michael@0: * Called after a container changes state. michael@0: * michael@0: * @param aContainerNode michael@0: * The container that has changed state. michael@0: * @param aOldState michael@0: * The state that aContainerNode has transitioned out of. michael@0: * @param aNewState michael@0: * The state that aContainerNode has transitioned into. michael@0: */ michael@0: void containerStateChanged(in nsINavHistoryContainerResultNode aContainerNode, michael@0: in unsigned long aOldState, michael@0: in unsigned long aNewState); michael@0: michael@0: /** michael@0: * Called when something significant has happened within the container. The michael@0: * contents of the container should be re-built. michael@0: * michael@0: * @param aContainerNode michael@0: * the container node to invalidate michael@0: */ michael@0: void invalidateContainer(in nsINavHistoryContainerResultNode aContainerNode); michael@0: michael@0: /** michael@0: * This is called to indicate to the UI that the sort has changed to the michael@0: * given mode. For trees, for example, this would update the column headers michael@0: * to reflect the sorting. For many other types of views, this won't be michael@0: * applicable. michael@0: * michael@0: * @param sortingMode One of nsINavHistoryQueryOptions.SORT_BY_* that michael@0: * indicates the new sorting mode. michael@0: * michael@0: * This only is expected to update the sorting UI. invalidateAll() will also michael@0: * get called if the sorting changes to update everything. michael@0: */ michael@0: void sortingChanged(in unsigned short sortingMode); michael@0: michael@0: /** michael@0: * This is called to indicate that a batch operation is about to start or end. michael@0: * The observer could want to disable some events or updates during batches, michael@0: * since multiple operations are packed in a short time. michael@0: * For example treeviews could temporarily suppress select notifications. michael@0: * michael@0: * @param aToggleMode michael@0: * true if a batch is starting, false if it's ending. michael@0: */ michael@0: void batching(in boolean aToggleMode); michael@0: michael@0: /** michael@0: * Called by the result when this observer is added. michael@0: */ michael@0: attribute nsINavHistoryResult result; michael@0: }; michael@0: michael@0: michael@0: /** michael@0: * TODO: Bug 517719. michael@0: * michael@0: * A predefined view adaptor for interfacing results with an nsITree. This michael@0: * object will remove itself from its associated result when the tree has been michael@0: * detached. This prevents circular references. Users should be aware of this, michael@0: * if you want to re-use the same viewer, you will need to keep your own michael@0: * reference to it and re-initialize it when the tree changes. If you use this michael@0: * object, attach it to a result, never attach it to a tree, and forget about michael@0: * it, it will leak! michael@0: */ michael@0: [scriptable, uuid(f8b518c0-1faf-11df-8a39-0800200c9a66)] michael@0: interface nsINavHistoryResultTreeViewer : nsINavHistoryResultObserver michael@0: { michael@0: /** michael@0: * This allows you to get at the real node for a given row index. This is michael@0: * only valid when a tree is attached. michael@0: */ michael@0: nsINavHistoryResultNode nodeForTreeIndex(in unsigned long aIndex); michael@0: michael@0: /** michael@0: * Reverse of nodeForFlatIndex, returns the row index for a given result node. michael@0: * Returns INDEX_INVISIBLE if the item is not visible (for example, its michael@0: * parent is collapsed). This is only valid when a tree is attached. The michael@0: * the result will always be INDEX_INVISIBLE if not. michael@0: * michael@0: * Note: This sounds sort of obvious, but it got me: aNode must be a node michael@0: * retrieved from the same result that this viewer is for. If you michael@0: * execute another query and get a node from a _different_ result, this michael@0: * function will always return the index of that node in the tree that michael@0: * is attached to that result. michael@0: */ michael@0: const unsigned long INDEX_INVISIBLE = 0xffffffff; michael@0: unsigned long treeIndexForNode(in nsINavHistoryResultNode aNode); michael@0: }; michael@0: michael@0: michael@0: /** michael@0: * The result of a history/bookmark query. michael@0: */ michael@0: [scriptable, uuid(c2229ce3-2159-4001-859c-7013c52f7619)] michael@0: interface nsINavHistoryResult : nsISupports michael@0: { michael@0: /** michael@0: * Sorts all nodes recursively by the given parameter, one of michael@0: * nsINavHistoryQueryOptions.SORT_BY_* This will update the corresponding michael@0: * options for this result, so that re-using the current options/queries will michael@0: * always give you the current view. michael@0: */ michael@0: attribute unsigned short sortingMode; michael@0: michael@0: /** michael@0: * The annotation to use in SORT_BY_ANNOTATION_* sorting modes, set this michael@0: * before setting the sortingMode attribute. michael@0: */ michael@0: attribute AUTF8String sortingAnnotation; michael@0: michael@0: /** michael@0: * Whether or not notifications on result changes are suppressed. michael@0: * Initially set to false. michael@0: * michael@0: * Use this to avoid flickering and to improve performance when you michael@0: * do temporary changes to the result structure (e.g. when searching for a michael@0: * node recursively). michael@0: */ michael@0: attribute boolean suppressNotifications; michael@0: michael@0: /** michael@0: * Adds an observer for changes done in the result. michael@0: * michael@0: * @param aObserver michael@0: * a result observer. michael@0: * @param aOwnsWeak michael@0: * If false, the result will keep an owning reference to the observer, michael@0: * which must be removed using removeObserver. michael@0: * If true, the result will keep a weak reference to the observer, which michael@0: * must implement nsISupportsWeakReference. michael@0: * michael@0: * @see nsINavHistoryResultObserver michael@0: */ michael@0: void addObserver(in nsINavHistoryResultObserver aObserver, in boolean aOwnsWeak); michael@0: michael@0: /** michael@0: * Removes an observer that was added by addObserver. michael@0: * michael@0: * @param aObserver michael@0: * a result observer that was added by addObserver. michael@0: */ michael@0: void removeObserver(in nsINavHistoryResultObserver aObserver); michael@0: michael@0: /** michael@0: * This is the root of the results. Remember that you need to open all michael@0: * containers for their contents to be valid. michael@0: * michael@0: * When a result goes out of scope it will continue to observe changes till michael@0: * it is cycle collected. While the result waits to be collected it will stay michael@0: * in memory, and continue to update itself, potentially causing unwanted michael@0: * additional work. When you close the root node the result will stop michael@0: * observing changes, so it is good practice to close the root node when you michael@0: * are done with a result, since that will avoid unwanted performance hits. michael@0: */ michael@0: readonly attribute nsINavHistoryContainerResultNode root; michael@0: }; michael@0: michael@0: michael@0: /** michael@0: * Similar to nsIRDFObserver for history. Note that we don't pass the data michael@0: * source since that is always the global history. michael@0: * michael@0: * DANGER! If you are in the middle of a batch transaction, there may be a michael@0: * database transaction active. You can still access the DB, but be careful. michael@0: */ michael@0: [scriptable, uuid(0f0f45b0-13a1-44ae-a0ab-c6046ec6d4da)] michael@0: interface nsINavHistoryObserver : nsISupports michael@0: { michael@0: /** michael@0: * Notifies you that a bunch of things are about to change, don't do any michael@0: * heavy-duty processing until onEndUpdateBatch is called. michael@0: */ michael@0: void onBeginUpdateBatch(); michael@0: michael@0: /** michael@0: * Notifies you that we are done doing a bunch of things and you should go michael@0: * ahead and update UI, etc. michael@0: */ michael@0: void onEndUpdateBatch(); michael@0: michael@0: /** michael@0: * Called when a resource is visited. This is called the first time a michael@0: * resource (page, image, etc.) is seen as well as every subsequent time. michael@0: * michael@0: * Normally, transition types of TRANSITION_EMBED (corresponding to images in michael@0: * a page, for example) are not displayed in history results (unless michael@0: * includeHidden is set). Many observers can ignore _EMBED notifications michael@0: * (which will comprise the majority of visit notifications) to save work. michael@0: * michael@0: * @param aVisitID ID of the visit that was just created. michael@0: * @param aTime Time of the visit michael@0: * @param aSessionID No longer supported (always set to 0). michael@0: * @param aReferringID The ID of the visit the user came from. 0 if empty. michael@0: * @param aTransitionType One of nsINavHistory.TRANSITION_* michael@0: * @param aGUID The unique ID associated with the page. michael@0: * @param aHidden Whether the visited page is marked as hidden. michael@0: */ michael@0: void onVisit(in nsIURI aURI, michael@0: in long long aVisitID, michael@0: in PRTime aTime, michael@0: in long long aSessionID, michael@0: in long long aReferringID, michael@0: in unsigned long aTransitionType, michael@0: in ACString aGUID, michael@0: in boolean aHidden); michael@0: michael@0: /** michael@0: * Called whenever either the "real" title or the custom title of the page michael@0: * changed. BOTH TITLES ARE ALWAYS INCLUDED in this notification, even though michael@0: * only one will change at a time. Often, consumers will want to display the michael@0: * user title if it is available, and fall back to the page title (the one michael@0: * specified in the tag of the page). michael@0: * michael@0: * Note that there is a difference between an empty title and a NULL title. michael@0: * An empty string means that somebody specifically set the title to be michael@0: * nothing. NULL means nobody set it. From C++: use IsVoid() and SetIsVoid() michael@0: * to see whether an empty string is "null" or not (it will always be an michael@0: * empty string in either case). michael@0: * michael@0: * @param aURI michael@0: * The URI of the page. michael@0: * @param aPageTitle michael@0: * The new title of the page. michael@0: * @param aGUID michael@0: * The unique ID associated with the page. michael@0: */ michael@0: void onTitleChanged(in nsIURI aURI, michael@0: in AString aPageTitle, michael@0: in ACString aGUID); michael@0: michael@0: /** michael@0: * Called when an individual page's frecency has changed. michael@0: * michael@0: * This is not called for pages whose frecencies change as the result of some michael@0: * large operation where some large or unknown number of frecencies change at michael@0: * once. Use onManyFrecenciesChanged to detect such changes. michael@0: * michael@0: * @param aURI michael@0: * The page's URI. michael@0: * @param aNewFrecency michael@0: * The page's new frecency. michael@0: * @param aGUID michael@0: * The page's GUID. michael@0: * @param aHidden michael@0: * True if the page is marked as hidden. michael@0: * @param aVisitDate michael@0: * The page's last visit date. michael@0: */ michael@0: void onFrecencyChanged(in nsIURI aURI, michael@0: in long aNewFrecency, michael@0: in ACString aGUID, michael@0: in boolean aHidden, michael@0: in PRTime aVisitDate); michael@0: michael@0: /** michael@0: * Called when the frecencies of many pages have changed at once. michael@0: * michael@0: * onFrecencyChanged is not called for each of those pages. michael@0: */ michael@0: void onManyFrecenciesChanged(); michael@0: michael@0: /** michael@0: * Removed by the user. michael@0: */ michael@0: const unsigned short REASON_DELETED = 0; michael@0: /** michael@0: * Removed by automatic expiration. michael@0: */ michael@0: const unsigned short REASON_EXPIRED = 1; michael@0: michael@0: /** michael@0: * This page and all of its visits are being deleted. Note: the page may not michael@0: * necessarily have actually existed for this function to be called. michael@0: * michael@0: * Delete notifications are only 99.99% accurate. Batch delete operations michael@0: * must be done in two steps, so first come notifications, then a bulk michael@0: * delete. If there is some error in the middle (for example, out of memory) michael@0: * then you'll get a notification and it won't get deleted. There's no easy michael@0: * way around this. michael@0: * michael@0: * @param aURI michael@0: * The URI that was deleted. michael@0: * @param aGUID michael@0: * The unique ID associated with the page. michael@0: * @param aReason michael@0: * Indicates the reason for the removal. see REASON_* constants. michael@0: */ michael@0: void onDeleteURI(in nsIURI aURI, michael@0: in ACString aGUID, michael@0: in unsigned short aReason); michael@0: michael@0: /** michael@0: * Notification that all of history is being deleted. michael@0: */ michael@0: void onClearHistory(); michael@0: michael@0: /** michael@0: * onPageChanged attribute indicating that favicon has been updated. michael@0: * aNewValue parameter will be set to the new favicon URI string. michael@0: */ michael@0: const unsigned long ATTRIBUTE_FAVICON = 3; michael@0: michael@0: /** michael@0: * An attribute of this page changed. michael@0: * michael@0: * @param aURI michael@0: * The URI of the page on which an attribute changed. michael@0: * @param aChangedAttribute michael@0: * The attribute whose value changed. See ATTRIBUTE_* constants. michael@0: * @param aNewValue michael@0: * The attribute's new value. michael@0: * @param aGUID michael@0: * The unique ID associated with the page. michael@0: */ michael@0: void onPageChanged(in nsIURI aURI, michael@0: in unsigned long aChangedAttribute, michael@0: in AString aNewValue, michael@0: in ACString aGUID); michael@0: michael@0: /** michael@0: * Called when some visits of an history entry are expired. michael@0: * michael@0: * @param aURI michael@0: * The page whose visits have been expired. michael@0: * @param aVisitTime michael@0: * The largest visit time in microseconds that has been expired. We michael@0: * guarantee that we don't have any visit older than this date. michael@0: * @param aGUID michael@0: * The unique ID associated with the page. michael@0: * michael@0: * @note: when all visits for a page are expired and also the full page entry michael@0: * is expired, you will only get an onDeleteURI notification. If a michael@0: * page entry is removed, then you can be sure that we don't have michael@0: * anymore visits for it. michael@0: * @param aReason michael@0: * Indicates the reason for the removal. see REASON_* constants. michael@0: * @param aTransitionType michael@0: * If it's a valid TRANSITION_* value, all visits of the specified type michael@0: * have been removed. michael@0: */ michael@0: void onDeleteVisits(in nsIURI aURI, michael@0: in PRTime aVisitTime, michael@0: in ACString aGUID, michael@0: in unsigned short aReason, michael@0: in unsigned long aTransitionType); michael@0: }; michael@0: michael@0: michael@0: /** michael@0: * This object encapsulates all the query parameters you're likely to need michael@0: * when building up history UI. All parameters are ANDed together. michael@0: * michael@0: * This is not intended to be a super-general query mechanism. This was designed michael@0: * so that most queries can be done in only one SQL query. This is important michael@0: * because, if the user has their profile on a networked drive, query latency michael@0: * can be non-negligible. michael@0: */ michael@0: michael@0: [scriptable, uuid(dc87ae79-22f1-4dcf-975b-852b01d210cb)] michael@0: interface nsINavHistoryQuery : nsISupports michael@0: { michael@0: /** michael@0: * Time range for results (INCLUSIVE). The *TimeReference is one of the michael@0: * constants TIME_RELATIVE_* which indicates how to interpret the michael@0: * corresponding time value. michael@0: * TIME_RELATIVE_EPOCH (default): michael@0: * The time is relative to Jan 1 1970 GMT, (this is a normal PRTime) michael@0: * TIME_RELATIVE_TODAY: michael@0: * The time is relative to this morning at midnight. Normally used for michael@0: * queries relative to today. For example, a "past week" query would be michael@0: * today-6 days -> today+1 day michael@0: * TIME_RELATIVE_NOW: michael@0: * The time is relative to right now. michael@0: * michael@0: * Note: PRTime is in MICROseconds since 1 Jan 1970. Javascript date objects michael@0: * are expressed in MILLIseconds since 1 Jan 1970. michael@0: * michael@0: * As a special case, a 0 time relative to TIME_RELATIVE_EPOCH indicates that michael@0: * the time is not part of the query. This is the default, so an empty query michael@0: * will match any time. The has* functions return whether the corresponding michael@0: * time is considered. michael@0: * michael@0: * You can read absolute*Time to get the time value that the currently loaded michael@0: * reference points + offset resolve to. michael@0: */ michael@0: const unsigned long TIME_RELATIVE_EPOCH = 0; michael@0: const unsigned long TIME_RELATIVE_TODAY = 1; michael@0: const unsigned long TIME_RELATIVE_NOW = 2; michael@0: michael@0: attribute PRTime beginTime; michael@0: attribute unsigned long beginTimeReference; michael@0: readonly attribute boolean hasBeginTime; michael@0: readonly attribute PRTime absoluteBeginTime; michael@0: michael@0: attribute PRTime endTime; michael@0: attribute unsigned long endTimeReference; michael@0: readonly attribute boolean hasEndTime; michael@0: readonly attribute PRTime absoluteEndTime; michael@0: michael@0: /** michael@0: * Text search terms. michael@0: */ michael@0: attribute AString searchTerms; michael@0: readonly attribute boolean hasSearchTerms; michael@0: michael@0: /** michael@0: * Set lower or upper limits for how many times an item has been michael@0: * visited. The default is -1, and in that case all items are michael@0: * matched regardless of their visit count. michael@0: */ michael@0: attribute long minVisits; michael@0: attribute long maxVisits; michael@0: michael@0: /** michael@0: * When the set of transitions is nonempty, results are limited to pages which michael@0: * have at least one visit for each of the transition types. michael@0: * @note: For searching on more than one transition this can be very slow. michael@0: * michael@0: * Limit results to the specified list of transition types. michael@0: */ michael@0: void setTransitions([const,array, size_is(count)] in unsigned long transitions, michael@0: in unsigned long count); michael@0: michael@0: /** michael@0: * Get the transitions set for this query. michael@0: */ michael@0: void getTransitions([optional] out unsigned long count, michael@0: [retval,array,size_is(count)] out unsigned long transitions); michael@0: michael@0: /** michael@0: * Get the count of the set query transitions. michael@0: */ michael@0: readonly attribute unsigned long transitionCount; michael@0: michael@0: /** michael@0: * When set, returns only bookmarked items, when unset, returns anything. Setting this michael@0: * is equivalent to listing all bookmark folders in the 'folders' parameter. michael@0: */ michael@0: attribute boolean onlyBookmarked; michael@0: michael@0: /** michael@0: * This controls the meaning of 'domain', and whether it is an exact match michael@0: * 'domainIsHost' = true, or hierarchical (= false). michael@0: */ michael@0: attribute boolean domainIsHost; michael@0: michael@0: /** michael@0: * This is the host or domain name (controlled by domainIsHost). When michael@0: * domainIsHost, domain only does exact matching on host names. Otherwise, michael@0: * it will return anything whose host name ends in 'domain'. michael@0: * michael@0: * This one is a little different than most. Setting it to an empty string michael@0: * is a real query and will match any URI that has no host name (local files michael@0: * and such). Set this to NULL (in C++ use SetIsVoid) if you don't want michael@0: * domain matching. michael@0: */ michael@0: attribute AUTF8String domain; michael@0: readonly attribute boolean hasDomain; michael@0: michael@0: /** michael@0: * Controls the interpretation of 'uri'. When unset (default), the URI will michael@0: * request an exact match of the specified URI. When set, any history entry michael@0: * beginning in 'uri' will match. For example "http://bar.com/foo" will match michael@0: * "http://bar.com/foo" as well as "http://bar.com/foo/baz.gif". michael@0: */ michael@0: attribute boolean uriIsPrefix; michael@0: michael@0: /** michael@0: * This is a URI to match, to, for example, find out every time you visited michael@0: * a given URI. Use uriIsPrefix to control whether this is an exact match. michael@0: */ michael@0: attribute nsIURI uri; michael@0: readonly attribute boolean hasUri; michael@0: michael@0: /** michael@0: * Test for existence or non-existence of a given annotation. We don't michael@0: * currently support >1 annotation name per query. If 'annotationIsNot' is michael@0: * true, we test for the non-existence of the specified annotation. michael@0: * michael@0: * Testing for not annotation will do the same thing as a normal query and michael@0: * remove everything that doesn't have that annotation. Asking for things michael@0: * that DO have a given annotation is a little different. It also includes michael@0: * things that have never been visited. This allows place queries to be michael@0: * returned as well as anything else that may have been tagged with an michael@0: * annotation. This will only work for RESULTS_AS_URI since there will be michael@0: * no visits for these items. michael@0: */ michael@0: attribute boolean annotationIsNot; michael@0: attribute AUTF8String annotation; michael@0: readonly attribute boolean hasAnnotation; michael@0: michael@0: /** michael@0: * Limit results to items that are tagged with all of the given tags. This michael@0: * attribute must be set to an array of strings. When called as a getter it michael@0: * will return an array of strings sorted ascending in lexicographical order. michael@0: * The array may be empty in either case. Duplicate tags may be specified michael@0: * when setting the attribute, but the getter returns only unique tags. michael@0: * michael@0: * To search for items that are tagged with any given tags rather than all, michael@0: * multiple queries may be passed to nsINavHistoryService.executeQueries(). michael@0: */ michael@0: attribute nsIVariant tags; michael@0: michael@0: /** michael@0: * If 'tagsAreNot' is true, the results are instead limited to items that michael@0: * are not tagged with any of the given tags. This attribute is used in michael@0: * conjunction with the 'tags' attribute. michael@0: */ michael@0: attribute boolean tagsAreNot; michael@0: michael@0: /** michael@0: * Limit results to items that are in all of the given folders. michael@0: */ michael@0: void getFolders([optional] out unsigned long count, michael@0: [retval,array,size_is(count)] out long long folders); michael@0: readonly attribute unsigned long folderCount; michael@0: michael@0: /** michael@0: * For the special result type RESULTS_AS_TAG_CONTENTS we can define only michael@0: * one folder that must be a tag folder. This is not recursive so results michael@0: * will be returned from the first level of that folder. michael@0: */ michael@0: void setFolders([const,array, size_is(folderCount)] in long long folders, michael@0: in unsigned long folderCount); michael@0: michael@0: /** michael@0: * Creates a new query item with the same parameters of this one. michael@0: */ michael@0: nsINavHistoryQuery clone(); michael@0: }; michael@0: michael@0: /** michael@0: * This object represents the global options for executing a query. michael@0: */ michael@0: [scriptable, uuid(8198dfa7-8061-4766-95cb-fa86b3c00a47)] michael@0: interface nsINavHistoryQueryOptions : nsISupports michael@0: { michael@0: /** michael@0: * You can ask for the results to be pre-sorted. Since the DB has indices michael@0: * of many items, it can produce sorted results almost for free. These should michael@0: * be self-explanatory. michael@0: * michael@0: * Note: re-sorting is slower, as is sorting by title or when you have a michael@0: * host name. michael@0: * michael@0: * For bookmark items, SORT_BY_NONE means sort by the natural bookmark order. michael@0: */ michael@0: const unsigned short SORT_BY_NONE = 0; michael@0: const unsigned short SORT_BY_TITLE_ASCENDING = 1; michael@0: const unsigned short SORT_BY_TITLE_DESCENDING = 2; michael@0: const unsigned short SORT_BY_DATE_ASCENDING = 3; michael@0: const unsigned short SORT_BY_DATE_DESCENDING = 4; michael@0: const unsigned short SORT_BY_URI_ASCENDING = 5; michael@0: const unsigned short SORT_BY_URI_DESCENDING = 6; michael@0: const unsigned short SORT_BY_VISITCOUNT_ASCENDING = 7; michael@0: const unsigned short SORT_BY_VISITCOUNT_DESCENDING = 8; michael@0: const unsigned short SORT_BY_KEYWORD_ASCENDING = 9; michael@0: const unsigned short SORT_BY_KEYWORD_DESCENDING = 10; michael@0: const unsigned short SORT_BY_DATEADDED_ASCENDING = 11; michael@0: const unsigned short SORT_BY_DATEADDED_DESCENDING = 12; michael@0: const unsigned short SORT_BY_LASTMODIFIED_ASCENDING = 13; michael@0: const unsigned short SORT_BY_LASTMODIFIED_DESCENDING = 14; michael@0: const unsigned short SORT_BY_TAGS_ASCENDING = 17; michael@0: const unsigned short SORT_BY_TAGS_DESCENDING = 18; michael@0: const unsigned short SORT_BY_ANNOTATION_ASCENDING = 19; michael@0: const unsigned short SORT_BY_ANNOTATION_DESCENDING = 20; michael@0: const unsigned short SORT_BY_FRECENCY_ASCENDING = 21; michael@0: const unsigned short SORT_BY_FRECENCY_DESCENDING = 22; michael@0: michael@0: /** michael@0: * "URI" results, one for each URI visited in the range. Individual result michael@0: * nodes will be of type "URI". michael@0: */ michael@0: const unsigned short RESULTS_AS_URI = 0; michael@0: michael@0: /** michael@0: * "Visit" results, with one for each time a page was visited (this will michael@0: * often give you multiple results for one URI). Individual result nodes will michael@0: * have type "Visit" michael@0: * michael@0: * @note This result type is only supported by QUERY_TYPE_HISTORY. michael@0: */ michael@0: const unsigned short RESULTS_AS_VISIT = 1; michael@0: michael@0: /** michael@0: * This is identical to RESULT_TYPE_VISIT except that individual result nodes michael@0: * will have type "FullVisit". This is used for the attributes that are not michael@0: * commonly accessed to save space in the common case (the lists can be very michael@0: * long). michael@0: * michael@0: * @note Not yet implemented. See bug 409662. michael@0: * @note This result type is only supported by QUERY_TYPE_HISTORY. michael@0: */ michael@0: const unsigned short RESULTS_AS_FULL_VISIT = 2; michael@0: michael@0: /** michael@0: * This returns query nodes for each predefined date range where we michael@0: * had visits. The node contains information how to load its content: michael@0: * - visits for the given date range will be loaded. michael@0: * michael@0: * @note This result type is only supported by QUERY_TYPE_HISTORY. michael@0: */ michael@0: const unsigned short RESULTS_AS_DATE_QUERY = 3; michael@0: michael@0: /** michael@0: * This returns nsINavHistoryQueryResultNode nodes for each site where we michael@0: * have visits. The node contains information how to load its content: michael@0: * - last visit for each url in the given host will be loaded. michael@0: * michael@0: * @note This result type is only supported by QUERY_TYPE_HISTORY. michael@0: */ michael@0: const unsigned short RESULTS_AS_SITE_QUERY = 4; michael@0: michael@0: /** michael@0: * This returns nsINavHistoryQueryResultNode nodes for each day where we michael@0: * have visits. The node contains information how to load its content: michael@0: * - list of hosts visited in the given period will be loaded. michael@0: * michael@0: * @note This result type is only supported by QUERY_TYPE_HISTORY. michael@0: */ michael@0: const unsigned short RESULTS_AS_DATE_SITE_QUERY = 5; michael@0: michael@0: /** michael@0: * This returns nsINavHistoryQueryResultNode nodes for each tag. michael@0: * The node contains information how to load its content: michael@0: * - list of bookmarks with the given tag will be loaded. michael@0: * michael@0: * @note Setting this resultType will force queryType to QUERY_TYPE_BOOKMARKS. michael@0: */ michael@0: const unsigned short RESULTS_AS_TAG_QUERY = 6; michael@0: michael@0: /** michael@0: * This is a container with an URI result type that contains the last michael@0: * modified bookmarks for the given tag. michael@0: * Tag folder id must be defined in the query. michael@0: * michael@0: * @note Setting this resultType will force queryType to QUERY_TYPE_BOOKMARKS. michael@0: */ michael@0: const unsigned short RESULTS_AS_TAG_CONTENTS = 7; michael@0: michael@0: /** michael@0: * The sorting mode to be used for this query. michael@0: * mode is one of SORT_BY_* michael@0: */ michael@0: attribute unsigned short sortingMode; michael@0: michael@0: /** michael@0: * The annotation to use in SORT_BY_ANNOTATION_* sorting modes. michael@0: */ michael@0: attribute AUTF8String sortingAnnotation; michael@0: michael@0: /** michael@0: * Sets the result type. One of RESULT_TYPE_* which includes how URIs are michael@0: * represented. michael@0: */ michael@0: attribute unsigned short resultType; michael@0: michael@0: /** michael@0: * This option excludes all URIs and separators from a bookmarks query. michael@0: * This would be used if you just wanted a list of bookmark folders and michael@0: * queries (such as the left pane of the places page). michael@0: * Defaults to false. michael@0: */ michael@0: attribute boolean excludeItems; michael@0: michael@0: /** michael@0: * Set to true to exclude queries ("place:" URIs) from the query results. michael@0: * Simple folder queries (bookmark folder symlinks) will still be included. michael@0: * Defaults to false. michael@0: */ michael@0: attribute boolean excludeQueries; michael@0: michael@0: /** michael@0: * Set to true to exclude read-only folders from the query results. This is michael@0: * designed for cases where you want to give the user the option of filing michael@0: * something into a list of folders. It only affects cases where the actual michael@0: * folder result node would appear in its parent folder and filters it out. michael@0: * It doesn't affect the query at all, and doesn't affect more complex michael@0: * queries (such as "folders with annotation X"). michael@0: */ michael@0: attribute boolean excludeReadOnlyFolders; michael@0: michael@0: /** michael@0: * When set, allows items with "place:" URIs to appear as containers, michael@0: * with the container's contents filled in from the stored query. michael@0: * If not set, these will appear as normal items. Doesn't do anything if michael@0: * excludeQueries is set. Defaults to false. michael@0: * michael@0: * Note that this has no effect on folder links, which are place: URIs michael@0: * returned by nsINavBookmarkService.GetFolderURI. These are always expanded michael@0: * and will appear as bookmark folders. michael@0: */ michael@0: attribute boolean expandQueries; michael@0: michael@0: /** michael@0: * Some pages in history are marked "hidden" and thus don't appear by default michael@0: * in queries. These include automatic framed visits and redirects. Setting michael@0: * this attribute will return all pages, even hidden ones. Does nothing for michael@0: * bookmark queries. Defaults to false. michael@0: */ michael@0: attribute boolean includeHidden; michael@0: michael@0: /** michael@0: * This is the maximum number of results that you want. The query is exeucted, michael@0: * the results are sorted, and then the top 'maxResults' results are taken michael@0: * and returned. Set to 0 (the default) to get all results. michael@0: * michael@0: * THIS DOES NOT WORK IN CONJUNCTION WITH SORTING BY TITLE. This is because michael@0: * sorting by title requires us to sort after using locale-sensetive sorting michael@0: * (as opposed to letting the database do it for us). michael@0: * michael@0: * Instead, we get the result ordered by date, pick the maxResult most recent michael@0: * ones, and THEN sort by title. michael@0: */ michael@0: attribute unsigned long maxResults; michael@0: michael@0: const unsigned short QUERY_TYPE_HISTORY = 0; michael@0: const unsigned short QUERY_TYPE_BOOKMARKS = 1; michael@0: /* Unified queries are not yet implemented. See bug 378798 */ michael@0: const unsigned short QUERY_TYPE_UNIFIED = 2; michael@0: michael@0: /** michael@0: * The type of search to use when querying the DB; This attribute is only michael@0: * honored by query nodes. It is silently ignored for simple folder queries. michael@0: */ michael@0: attribute unsigned short queryType; michael@0: michael@0: /** michael@0: * When this is true, the root container node generated by these options and michael@0: * its descendant containers will be opened asynchronously if they support it. michael@0: * This is false by default. michael@0: * michael@0: * @note Currently only bookmark folder containers support being opened michael@0: * asynchronously. michael@0: */ michael@0: attribute boolean asyncEnabled; michael@0: michael@0: /** michael@0: * Creates a new options item with the same parameters of this one. michael@0: */ michael@0: nsINavHistoryQueryOptions clone(); michael@0: }; michael@0: michael@0: [scriptable, uuid(baebc597-9daf-4103-a325-e41ef9e7608a)] michael@0: interface nsINavHistoryService : nsISupports michael@0: { michael@0: /** michael@0: * System Notifications: michael@0: * michael@0: * places-init-complete - Sent once the History service is completely michael@0: * initialized successfully. michael@0: * places-database-locked - Sent if initialization of the History service michael@0: * failed due to the inability to open the places.sqlite michael@0: * for access reasons. michael@0: */ michael@0: michael@0: /** michael@0: * This transition type means the user followed a link and got a new toplevel michael@0: * window. michael@0: */ michael@0: const unsigned long TRANSITION_LINK = 1; michael@0: michael@0: /** michael@0: * This transition type means that the user typed the page's URL in the michael@0: * URL bar or selected it from URL bar autocomplete results, clicked on michael@0: * it from a history query (from the History sidebar, History menu, michael@0: * or history query in the personal toolbar or Places organizer. michael@0: */ michael@0: const unsigned long TRANSITION_TYPED = 2; michael@0: michael@0: /** michael@0: * This transition is set when the user followed a bookmark to get to the michael@0: * page. michael@0: */ michael@0: const unsigned long TRANSITION_BOOKMARK = 3; michael@0: michael@0: /** michael@0: * This transition type is set when some inner content is loaded. This is michael@0: * true of all images on a page, and the contents of the iframe. It is also michael@0: * true of any content in a frame if the user did not explicitly follow michael@0: * a link to get there. michael@0: */ michael@0: const unsigned long TRANSITION_EMBED = 4; michael@0: michael@0: /** michael@0: * Set when the transition was a permanent redirect. michael@0: */ michael@0: const unsigned long TRANSITION_REDIRECT_PERMANENT = 5; michael@0: michael@0: /** michael@0: * Set when the transition was a temporary redirect. michael@0: */ michael@0: const unsigned long TRANSITION_REDIRECT_TEMPORARY = 6; michael@0: michael@0: /** michael@0: * Set when the transition is a download. michael@0: */ michael@0: const unsigned long TRANSITION_DOWNLOAD = 7; michael@0: michael@0: /** michael@0: * This transition type means the user followed a link and got a visit in michael@0: * a frame. michael@0: */ michael@0: const unsigned long TRANSITION_FRAMED_LINK = 8; michael@0: michael@0: /** michael@0: * Set when database is coherent michael@0: */ michael@0: const unsigned short DATABASE_STATUS_OK = 0; michael@0: michael@0: /** michael@0: * Set when database did not exist and we created a new one michael@0: */ michael@0: const unsigned short DATABASE_STATUS_CREATE = 1; michael@0: michael@0: /** michael@0: * Set when database was corrupt and we replaced it michael@0: */ michael@0: const unsigned short DATABASE_STATUS_CORRUPT = 2; michael@0: michael@0: /** michael@0: * Set when database schema has been upgraded michael@0: */ michael@0: const unsigned short DATABASE_STATUS_UPGRADED = 3; michael@0: michael@0: /** michael@0: * Returns the current database status michael@0: */ michael@0: readonly attribute unsigned short databaseStatus; michael@0: michael@0: /** michael@0: * True if there is any history. This can be used in UI to determine whether michael@0: * the "clear history" button should be enabled or not. This is much better michael@0: * than using BrowserHistory.count since that can be very slow if there is michael@0: * a lot of history (it must enumerate each item). This is pretty fast. michael@0: */ michael@0: readonly attribute boolean hasHistoryEntries; michael@0: michael@0: /** michael@0: * Gets the original title of the page. michael@0: * @deprecated use mozIAsyncHistory.getPlacesInfo instead. michael@0: */ michael@0: AString getPageTitle(in nsIURI aURI); michael@0: michael@0: /** michael@0: * This is just like markPageAsTyped (in nsIBrowserHistory, also implemented michael@0: * by the history service), but for bookmarks. It declares that the given URI michael@0: * is being opened as a result of following a bookmark. If this URI is loaded michael@0: * soon after this message has been received, that transition will be marked michael@0: * as following a bookmark. michael@0: */ michael@0: void markPageAsFollowedBookmark(in nsIURI aURI); michael@0: michael@0: /** michael@0: * Designates the url as having been explicitly typed in by the user. michael@0: * michael@0: * @param aURI michael@0: * URI of the page to be marked. michael@0: */ michael@0: void markPageAsTyped(in nsIURI aURI); michael@0: michael@0: /** michael@0: * Designates the url as coming from a link explicitly followed by michael@0: * the user (for example by clicking on it). michael@0: * michael@0: * @param aURI michael@0: * URI of the page to be marked. michael@0: */ michael@0: void markPageAsFollowedLink(in nsIURI aURI); michael@0: michael@0: /** michael@0: * Gets the stored character-set for an URI. michael@0: * michael@0: * @param aURI michael@0: * URI to retrieve character-set for michael@0: * @return character-set, empty string if not found michael@0: */ michael@0: AString getCharsetForURI(in nsIURI aURI); michael@0: michael@0: /** michael@0: * Sets the character-set for an URI. michael@0: * michael@0: * @param aURI michael@0: * URI to set the character-set for michael@0: * @param aCharset michael@0: * character-set to be set michael@0: */ michael@0: void setCharsetForURI(in nsIURI aURI, in AString aCharset); michael@0: michael@0: /** michael@0: * Returns true if this URI would be added to the history. You don't have to michael@0: * worry about calling this, adding a visit will always check before michael@0: * actually adding the page. This function is public because some components michael@0: * may want to check if this page would go in the history (i.e. for michael@0: * annotations). michael@0: */ michael@0: boolean canAddURI(in nsIURI aURI); michael@0: michael@0: /** michael@0: * This returns a new query object that you can pass to executeQuer[y/ies]. michael@0: * It will be initialized to all empty (so using it will give you all history). michael@0: */ michael@0: nsINavHistoryQuery getNewQuery(); michael@0: michael@0: /** michael@0: * This returns a new options object that you can pass to executeQuer[y/ies] michael@0: * after setting the desired options. michael@0: */ michael@0: nsINavHistoryQueryOptions getNewQueryOptions(); michael@0: michael@0: /** michael@0: * Executes a single query. michael@0: */ michael@0: nsINavHistoryResult executeQuery(in nsINavHistoryQuery aQuery, michael@0: in nsINavHistoryQueryOptions options); michael@0: michael@0: /** michael@0: * Executes an array of queries. All of the query objects are ORed michael@0: * together. Within a query, all the terms are ANDed together as in michael@0: * executeQuery. See executeQuery() michael@0: */ michael@0: nsINavHistoryResult executeQueries( michael@0: [array,size_is(aQueryCount)] in nsINavHistoryQuery aQueries, michael@0: in unsigned long aQueryCount, michael@0: in nsINavHistoryQueryOptions options); michael@0: michael@0: /** michael@0: * Converts a query URI-like string to an array of actual query objects for michael@0: * use to executeQueries(). The output query array may be empty if there is michael@0: * no information. However, there will always be an options structure returned michael@0: * (if nothing is defined, it will just have the default values). michael@0: */ michael@0: void queryStringToQueries(in AUTF8String aQueryString, michael@0: [array, size_is(aResultCount)] out nsINavHistoryQuery aQueries, michael@0: out unsigned long aResultCount, michael@0: out nsINavHistoryQueryOptions options); michael@0: michael@0: /** michael@0: * Converts a query into an equivalent string that can be persisted. Inverse michael@0: * of queryStringToQueries() michael@0: */ michael@0: AUTF8String queriesToQueryString( michael@0: [array, size_is(aQueryCount)] in nsINavHistoryQuery aQueries, michael@0: in unsigned long aQueryCount, michael@0: in nsINavHistoryQueryOptions options); michael@0: michael@0: /** michael@0: * Adds a history observer. If ownsWeak is false, the history service will michael@0: * keep an owning reference to the observer. If ownsWeak is true, then michael@0: * aObserver must implement nsISupportsWeakReference, and the history service michael@0: * will keep a weak reference to the observer. michael@0: */ michael@0: void addObserver(in nsINavHistoryObserver observer, in boolean ownsWeak); michael@0: michael@0: /** michael@0: * Removes a history observer. michael@0: */ michael@0: void removeObserver(in nsINavHistoryObserver observer); michael@0: michael@0: /** michael@0: * Runs the passed callback in batch mode. Use this when a lot of things michael@0: * are about to change. Calls can be nested, observers will only be michael@0: * notified when all batches begin/end. michael@0: * michael@0: * @param aCallback michael@0: * nsINavHistoryBatchCallback interface to call. michael@0: * @param aUserData michael@0: * Opaque parameter passed to nsINavBookmarksBatchCallback michael@0: */ michael@0: void runInBatchMode(in nsINavHistoryBatchCallback aCallback, michael@0: in nsISupports aClosure); michael@0: michael@0: /** michael@0: * True if history is disabled. currently, michael@0: * history is disabled if the places.history.enabled pref is false. michael@0: */ michael@0: readonly attribute boolean historyDisabled; michael@0: }; michael@0: michael@0: /** michael@0: * @see runInBatchMode of nsINavHistoryService/nsINavBookmarksService michael@0: */ michael@0: [scriptable, uuid(5143f2bb-be0a-4faf-9acb-b0ed3f82952c)] michael@0: interface nsINavHistoryBatchCallback : nsISupports { michael@0: void runBatched(in nsISupports aUserData); michael@0: };