diff options
Diffstat (limited to 'toolkit/components/places/nsINavHistoryService.idl')
| -rw-r--r-- | toolkit/components/places/nsINavHistoryService.idl | 1451 |
1 files changed, 1451 insertions, 0 deletions
diff --git a/toolkit/components/places/nsINavHistoryService.idl b/toolkit/components/places/nsINavHistoryService.idl new file mode 100644 index 000000000..3fd851870 --- /dev/null +++ b/toolkit/components/places/nsINavHistoryService.idl @@ -0,0 +1,1451 @@ +/* -*- 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; + + /** + * The unique ID associated with the history visit. For node types other than + * history visit nodes, this value is -1. + */ + readonly attribute long long visitId; + + /** + * The unique ID associated with visit node which was the referrer of this + * history visit. For node types other than history visit nodes, or visits + * without any known referrer, this value is -1. + */ + readonly attribute long long fromVisitId; + + /** + * The transition type associated with this visit. For node types other than + * history visit nodes, this value is 0. + */ + readonly attribute unsigned long visitType; +}; + + +/** + * 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(3E9CC95F-0D93-45F1-894F-908EEB9866D7)] +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); +}; + + +/** + * 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(62817759-4FEE-44A3-B58C-3E2F5AFC9D0A)] +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 queries and folder shortcut queries, this is set to + * the concrete itemId of the folder (i.e. for folder shortcuts it's the + * target folder id). Otherwise, this is set to -1. + */ + readonly attribute long long folderItemId; + + /** + * For both simple folder queries and folder shortcut queries, this is set to + * the concrete guid of the folder (i.e. for folder shortcuts it's the target + * folder guid). Otherwise, this is set to an empty string. + */ + readonly attribute ACString targetFolderGuid; +}; + + +/** + * 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 everytime a URI is visited. + * + * @note TRANSITION_EMBED visits (corresponding to images in a page, for + * example) are not displayed in history results. Most observers can + * ignore TRANSITION_EMBED visit 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 and always set to 0. + * @param aReferrerVisitId + * The id of the visit the user came from, defaults to 0 for no referrer. + * @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. + * @param aVisitCount + * Number of visits (included this one) for this URI. + * @param aTyped + * Whether the URI has been typed or not. + * TODO (Bug 1271801): This will become a count, rather than a boolean. + * For future compatibility, always compare it with "> 0". + */ + void onVisit(in nsIURI aURI, + in long long aVisitId, + in PRTime aTime, + in long long aSessionId, + in long long aReferrerVisitId, + in unsigned long aTransitionType, + in ACString aGuid, + in boolean aHidden, + in unsigned long aVisitCount, + in unsigned long aTyped); + + /** + * 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; + + /** + * This is a URI to match, to, for example, find out every time you visited + * a given URI. 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; + + /** + * DO NOT USE THIS API. IT'LL BE REMOVED IN BUG 1072833. + * + * Set to true to exclude live bookmarks from the query results. + */ + 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(8a1f527e-c9d7-4a51-bf0c-d86f0379b701)] +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; + + /** + * This transition type means the page has been reloaded. + */ + const unsigned long TRANSITION_RELOAD = 9; + + /** + * 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); + + /** + * 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); + + /** + * Gets an array of registered nsINavHistoryObserver objects. + */ + void getObservers([optional] out unsigned long count, + [retval, array, size_is(count)] out nsINavHistoryObserver observers); + + /** + * 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; + + /** + * Clear all TRANSITION_EMBED visits. + */ + void clearEmbedVisits(); +}; + +/** + * @see runInBatchMode of nsINavHistoryService/nsINavBookmarksService + */ +[scriptable, function, uuid(5a5a9154-95ac-4e3d-90df-558816297407)] +interface nsINavHistoryBatchCallback : nsISupports { + void runBatched(in nsISupports aUserData); +}; |