/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ /* ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is Places code. * * The Initial Developer of the Original Code is * Google Inc. * Portions created by the Initial Developer are Copyright (C) 2005 * the Initial Developer. All Rights Reserved. * * Contributor(s): * Brett Wilson * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ #include "nsISupports.idl" #include "nsIArray.idl" #include "nsIURI.idl" interface nsIFile; interface nsINavHistoryContainerResultNode; interface nsINavHistoryQueryResultNode; interface nsINavHistoryFolderResultNode; interface nsINavHistoryQuery; interface nsINavHistoryQueryOptions; interface nsINavHistoryResult; interface nsITreeColumn; interface nsIWritablePropertyBag; [scriptable, uuid(acae2b2d-5fcd-4419-b1bc-b7dc92a1836c)] interface nsINavHistoryResultNode : nsISupports { /** * Indentifies the parent result node in the result set. This is null for * top level nodes. */ readonly attribute nsINavHistoryContainerResultNode parent; /** * 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. The remote_container one * is a little weird, it is a temportary folder generated by the remote * container API. Note that bookmark folders can also be filled by the * remote container API (these are the entrypoints for the API) and may * have a remote container type as well. */ const PRUint32 RESULT_TYPE_URI = 0; // nsINavHistoryResultNode const PRUint32 RESULT_TYPE_VISIT = 1; // nsINavHistoryVisitResultNode const PRUint32 RESULT_TYPE_FULL_VISIT = 2; // nsINavHistoryFullVisitResultNode const PRUint32 RESULT_TYPE_HOST = 3; // nsINavHistoryContainerResultNode const PRUint32 RESULT_TYPE_REMOTE_CONTAINER = 4; // nsINavHistoryContainerResultNode const PRUint32 RESULT_TYPE_QUERY = 5; // nsINavHistoryQueryResultNode const PRUint32 RESULT_TYPE_FOLDER = 6; // nsINavHistoryFolderResultNode const PRUint32 RESULT_TYPE_SEPARATOR = 7; // nsINavHistoryResultNode readonly attribute PRUint32 type; /** * Title of the web page, or of the node's grouping (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 PRUint32 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, this is midnight on the morning of the day in question in * UTC time. */ 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 nsIURI 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. */ readonly attribute PRUint32 indentLevel; /** * Value with undefined meaning for use by the view. Its initial value will * be -1. The tree view uses this value to indicate the row in the tree that * this node is at. Other views may use this value however they choose. */ attribute PRInt32 viewIndex; /** * You can use this to associate temporary information with the result node. * This property bag is associated with the result node and is not persisted * in any way. */ readonly attribute nsIWritablePropertyBag propertyBag; /** * 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 PRInt32 bookmarkIndex; }; /** * When you request RESULT_TYPE_VISIT from query options, you will get this * interface for each item, which includes the session ID so that we can * group items from the same session together. */ [scriptable, uuid(8e2c5a86-b33d-4fa6-944b-559af7e95fcd)] interface nsINavHistoryVisitResultNode : nsINavHistoryResultNode { /** * This indicates the session ID of the * visit. This is used for session * grouping when a tree view is sorted by date. */ readonly attribute PRInt64 sessionId; }; /** * This structure will be returned when you request RESULT_TYPE_FULL_VISIT in * the query options. This includes uncommonly used information about each * visit. */ [scriptable, uuid(c49fd9d5-56e2-43eb-932c-f933f28cba85)] interface nsINavHistoryFullVisitResultNode : nsINavHistoryVisitResultNode { /** * This indicates the visit ID of the visit. */ readonly attribute PRInt64 visitId; /** * This indicates the referring visit ID of the visit. The referrer should * have the same sessionId. */ readonly attribute PRInt64 referringVisitId; /** * Indicates the transition type of the visit. * One of nsINavHistoryService.TRANSITION_* */ readonly attribute PRInt32 transitionType; }; /** * 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(957065fd-76e7-4c24-9284-c31b5decbaaa)] 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; /** * 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. */ readonly attribute PRUint32 childCount; nsINavHistoryResultNode getChild(in PRUint32 index); /** * Returns false if this node's list of children can be modified * (adding or removing children, or reordering children), or true if * the UI should not allow the list of children to be modified. * This is false for bookmark folder nodes unless setFolderReadOnly() has * been called to override it, and true for non-folder nodes. If this * container is a remote container this flag may be redefined by the * remote container provider. */ readonly attribute boolean childrenReadOnly; // -------------------------------------------------------------------------- // Remote container /** * This is a string representing the remote container API service that is * responsible for this container. It is empty if there is none. The * container may be a RESULT_TYPE_REMOTE_CONTAINER node that has been * dynamically generated by the remote container API. It may also be a * bookmark folder (RESULT_TYPE_FOLDER) for which some service (such as * livemarks) has registered to provide certain operations. */ readonly attribute AUTF8String remoteContainerType; /** * Appends a full visit node to this container and returns it. For the remote * container API. TO BE CALLED FROM nsIRemoteContainer::OnContainerOpening() * ONLY, and only for non-bookmark-folder containers. * * @see nsINavHistoryURIResultNode for parameters. * * UNTESTED: Container API functions are commented out until we can test */ /*nsINavHistoryResultNode appendURINode( in AUTF8String aURI, in AUTF8String aTitle, in PRUint32 aAccessCount, in PRTime aTime, in AUTF8String aIconURI);*/ /** * Appends a full visit node to this container and returns it. For the remote * container API. TO BE CALLED FROM nsIRemoteContainer::OnContainerOpening() * ONLY, and only for non-bookmark-folder containers. * * @see nsINavHistoryVisitResultNode for parameters. * * UNTESTED: Container API functions are commented out until we can test */ /*nsINavHistoryVisitResultNode appendVisitNode( in AUTF8String aURI, in AUTF8String aTitle, in PRUint32 aAccessCount, in PRTime aTime, in AUTF8String aIconURI, in PRInt64 aSession);*/ /** * Appends a full visit node to this container and returns it. For the remote * container API. TO BE CALLED FROM nsIRemoteContainer::OnContainerOpening() * ONLY, and only for non-bookmark-folder containers. * * @see nsINavHistoryFullVisitResultNode for parameters. * * UNTESTED: Container API functions are commented out until we can test */ /*nsINavHistoryFullVisitResultNode appendFullVisitNode( in AUTF8String aURI, in AUTF8String aTitle, in PRUint32 aAccessCount, in PRTime aTime, in AUTF8String aIconURI, in PRInt64 aSession, in PRInt64 aVisitId, in PRInt64 aReferringVisitId, in PRInt32 aTransitionType);*/ /** * Appends a container node to this container and returns it. For the remote * container API. TO BE CALLED FROM nsIRemoteContainer::OnContainerOpening() * ONLY, and only for non-bookmark-folder containers. * * aContainerType should be either RESULT_TYPE_HOST or * RESULT_TYPE_REMOTE_CONTAINER. When type is remote container you must * specify a remote container type, otherwise, the remote container type must * be null. Use appendQueryNode and appendFolderNode for the other container * types. * * UNTESTED: Container API functions are commented out until we can test */ /*nsINavHistoryContainerResultNode appendContainerNode( in AUTF8String aTitle, in AUTF8String aIconURI, in PRUint32 aContainerType, in AUTF8String aRemoteContainerType);*/ /** * Appends a query node to this container and returns it. For the remote * container API. TO BE CALLED FROM nsIRemoteContainer::OnContainerOpening() * ONLY, and only for non-bookmark-folder containers. * * Normally you should supply an empty string for IconURI and it will take * the default query icon for the current theme. * * UNTESTED: Container API functions are commented out until we can test */ /*nsINavHistoryQueryResultNode appendQueryNode( in AUTF8String aQueryURI, in AUTF8String aTitle, in AUTF8String aIconURI);*/ /** * Appends a bookmark folder node to this container and returns it. For the * remote container API. TO BE CALLED FROM nsIRemoteContainer::OnContainerOpening() * ONLY, and only for non-bookmark-folder containers. * * All container attributes will come from the boomkarks service for this * folder. * * UNTESTED: Container API functions are commented out until we can test */ /*nsINavHistoryFolderResultNode appendFolderNode(in PRInt64 aFolderId);*/ /** * Clears all children of this container. For the remote container API. * TO BE CALLED FROM nsIRemoteContainer::OnContainerOpening and * nsIRemoteContainer::OnContainerClosed ONLY, and valid only for * non-bookmark-folder containers. * * UNTESTED: Container API functions are commented out until we can test */ /*void clearContents();*/ }; /** * 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(dcd6a2b7-3d50-4c78-b1cb-2f0f18ac5864)] interface nsINavHistoryQueryResultNode : nsINavHistoryContainerResultNode { /** * Get the queries which build this node's children. * Only valid for RESULT_TYPE_QUERY nodes. */ void getQueries(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; }; /** * Represents a bookmark folder (type == RESULT_TYPE_FOLDER). It derives from a * query result because it can provide a query that will result in the * contents. */ [scriptable, uuid(f3160bfe-ebb3-453b-b25e-19d0b9c425b1)] interface nsINavHistoryFolderResultNode : nsINavHistoryQueryResultNode { /** * ID of the folder corresponding to this node. * Only valid for RESULT_TYPE_QUERY nodes where exactly one folder * has been specified in the query. 0 in all other cases. */ readonly attribute PRInt64 folderId; }; /** * Allows clients of the HistoryResult to define domain specific handling * of specific nsITreeView methods that the HistoryResult does not implement. * * @see nsINavHistoryResult for where this fits in */ [scriptable, uuid(b34d5ca4-ce8e-49a6-9201-a59ae2128d2c)] interface nsINavHistoryResultViewObserver : nsISupports { const long DROP_BEFORE = -1; const long DROP_ON = 0; const long DROP_AFTER = 1; /** * Methods used by the drag feedback code to determine if a drag is allowable at * the current location. To get the behavior where drops are only allowed on * items, such as the mailNews folder pane, always return false whe * the orientation is not DROP_ON. Implementors should not change the content of * the observer list! */ boolean canDrop(in long index, in long orientation); /** * Called when the user drops something on this view. The |orientation| param * specifies before/on/after the given |row|. */ void onDrop(in long row, in long orientation); /** * Called when an item is opened or closed. */ void onToggleOpenState (in long index); /** * Called when a header is clicked. */ void onCycleHeader(in nsITreeColumn column); /** * Called when a cell in a non-selectable cycling column (e.g. * unread/flag/etc.) is clicked. */ void onCycleCell(in long row, in nsITreeColumn column); /** * Called when selection in the tree changes */ void onSelectionChanged(); /** * A command API that can be used to invoke commands on the selection. * The tree will automatically invoke this method when certain keys * are pressed. For example, when the DEL key is pressed, performAction * will be called with the "delete" string. */ void onPerformAction(in wstring action); /** * A command API that can be used to invoke commands on a specific row. */ void onPerformActionOnRow(in wstring action, in long row); /** * A command API that can be used to invoke commands on a specific cell. */ void onPerformActionOnCell(in wstring action, in long row, in nsITreeColumn column); }; /** * 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 registerView * * @see nsINavHistoryResult for where this fits in */ [scriptable, uuid(11032c23-a9fd-4918-bc8f-004726a748da)] interface nsINavHistoryResultViewer : nsISupports { /** * Called when 'item' is inserted into 'parent' at index 'newIndex'. 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 itemInserted(in nsINavHistoryContainerResultNode parent, in nsINavHistoryResultNode item, in PRUint32 newIndex); /** * Called whan 'item' is removed from 'parent' at 'oldIndex'. 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 itemRemoved(in nsINavHistoryContainerResultNode parent, in nsINavHistoryResultNode item, in PRUint32 oldIndex); /** * Called when an item has been changed and should be repainted. This only * refers to the specific item. If it is a container, getting this message * does not imply anything happened to the children. You'll get separate * messages for those. Also, this may be called for container nodes at times * when the result thinks it's possible that a twisty mey need to bw redrawn. */ void itemChanged(in nsINavHistoryResultNode item); /** * Called when an item is being replaced with another item at the exact * same position. */ void itemReplaced(in nsINavHistoryContainerResultNode parent, in nsINavHistoryResultNode oldItem, in nsINavHistoryResultNode newItem, in PRUint32 index); /** * Called after a container node went from closed to opened. */ void containerOpened(in nsINavHistoryContainerResultNode item); /** * Called after a container node went from opened to closed. This will be * called for the topmost container that is closing, and implies that any * child containers have closed as well. */ void containerClosed(in nsINavHistoryContainerResultNode item); /** * Called when something significant has happened within the container. The * contents of the container should be re-built. */ void invalidateContainer(in nsINavHistoryContainerResultNode item); /** * Called when something significant is changing that requires everything * to be recomputed. For example, changing sorting or changing collapse * duplicates can affect every row. */ void invalidateAll(); /** * 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 PRUint32 sortingMode); /** * Called by the result when this object is set using * nsINavHistoryResult.viewer. This will be set to NULL when the result * is being deallocated. This should not be set by other code. */ attribute nsINavHistoryResult result; /** * Adds the specified view observer to the view. In ownsWeak is false, then * the result will hold a strong reference to the observer. If ownsWeak is * true, then the observer must implement nsISupportsWeakReference, and the * result will hold a weak reference to the observer. */ void addViewObserver(in nsINavHistoryResultViewObserver observer, in boolean ownsWeak); /** * Removes the specified view observer from this view. This observer must * have been previously registered using addViewObserver. */ void removeViewObserver(in nsINavHistoryResultViewObserver observer); }; /** * 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(ecd6ad22-8eb0-4824-8a57-5edad9a08ae6)] interface nsINavHistoryResultTreeViewer : nsINavHistoryResultViewer { /** * Controls whether duplicate adjacent elements are collapsed into a single * item in the tree. This prevents you from seeing multiple entries for * things when you have selected to get visits. When you sort by date, the * multiple entries will then appear because they will be separated (unless * you clicked reload a bunch of times in a row). If you know you'll only * ever want one entry per site, you should ask for URIs back instead of * visits so it will be more efficient. * Default = true * * Changing this value is somewhat heavyweight since it will force a tree * refresh. */ attribute boolean collapseDuplicates; /** * This tells you how many items are in the flattened list of results, i.e. * how many rows are in this tree right now. The tree adaptor will also * QI to nsITreeView, and this will be the same as nsITreeView.rowCount. * This is only valid when a tree is attached, the result will be 0 otherwise. */ readonly attribute PRUint32 flatItemCount; /** * 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 PRUint32 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 PRUint32 INDEX_INVISIBLE = 0xffffffff; PRUint32 treeIndexForNode(in nsINavHistoryResultNode aNode); }; /** * The result of a history/bookmark query. * * Use the "root" element to access the children of this query. * * The basic design of the system is a model-view-controller. This result object * represents the model where the data is stored. External components * provide the view and controller which define how the data looks and how * interaction happens. * +-- nsINavHistoryResultViewObserver * | * [RESULT]----->[viewer]----->[controller] * | * +-- nsINavHistoryResultViewer * * The result indicates to the view when something changes through the * nsINavHistoryResultViewer interface. Viewers register themselves through * the nsINavHistoryResult.RegisterViewer. The viewer interface would then tell * the actual view object what to do. A nsINavHistoryResultTreeViewer is * provided which provides pre-packaged interaction with a nsITreeBoxObject. * Other views will need to provide their own viewer interfaces. * * The viewer provides notifications to the controller when view events occur * through the nsINavHistoryResultViewObserver interface. */ [scriptable, uuid(25b45a94-3323-4c7b-910a-315f2c59bfb4)] 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 PRUint32 sortingMode; /** * The viewer for this result (see comment for the class for how these * objects are related). This may be null, in which case you can still * manually walk the tree using the root node. When this is non-null, you * can access the flattened list of items (flatItemCount, nodeForFlatIndex, * flatIndexForNode). */ attribute nsINavHistoryResultViewer viewer; /** * This is the root of the results. It will either be a * nsINavHistoryFolderResultNode (if the query is for bookmarks matching a * single folder) or just a nsINavHistoryQueryResultNode (for everything * else). Remember that you need to open all containers for their contents * to be valid. */ readonly attribute nsINavHistoryQueryResultNode 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(849e2184-3dee-416f-91cd-6a619ca49d1c)] interface nsINavHistoryObserver : nsISupports { /** * Notifies you that a bunch of things are about to change, don't do any * heavy-duty processing until onEndUpdateBatch is called. */ void onBeginUpdateBatch(); /** * Notifies you that we are done doing a bunch of things and you should go * ahead and update UI, etc. */ void onEndUpdateBatch(); /** * Called when a resource is visited. This is called the first time a * resource (page, image, etc.) is seen as well as every subsequent time. * * Normally, transition types of TRANSITION_EMBED (corresponding to images in * a page, for example) are not displayed in history results (unless * includeHidden is set). Many observers can ignore _EMBED notifications * (which will comprise the majority of visit notifications) to save work. * * @param aVisitID ID of the visit that was just created. * @param aTime Time of the visit * @param aSessionID The ID of one connected sequence of visits. * @param aReferringID The ID of the visit the user came from. 0 if empty. * @param aTransitionType One of nsINavHistory.TRANSITION_* */ void onVisit(in nsIURI aURI, in PRInt64 aVisitID, in PRTime aTime, in PRInt64 aSessionID, in PRInt64 aReferringID, in PRUint32 aTransitionType); /** * 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 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 aUserTitleChanged Is true if the user title was the thing that was * changed. If false, that means the "real" page * title was changed instead. */ void onTitleChanged(in nsIURI aURI, in AString aPageTitle, in AString aUserTitle, in PRBool aUserTitleChanged); /** * 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. */ void onDeleteURI(in nsIURI aURI); /** * Notification that all of history is being deleted. */ void onClearHistory(); /** * A page has had some attribute on it changed. Note that for TYPED and * HIDDEN, the page may not necessarily have been added yet. */ const PRUint32 ATTRIBUTE_FAVICON = 3; // favicon updated, aString = favicon annotation URI void onPageChanged(in nsIURI aURI, in PRUint32 aWhat, in AString aValue); /** * Called when a history entry expires. You will recieve notifications that * a specific visit has expired with the time of that visit. When the last * visit for a history entry expires, the history entry itself is deleted * and aWholeEntry is set. (If your observer only cares about URLs and not * specific visits, it needs only to listen for aWholeEntry notifications). * * It is possible for a history entry to be deleted that has no visits if * something is out of sync or after a bookmark is deleted that has no * visits (thus freeing the history entry). In these cases, aVisitTime will * be 0. */ void onPageExpired(in nsIURI aURI, in PRTime aVisitTime, in boolean aWholeEntry); }; /** * 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(884819a6-1860-4a71-8fd7-89d962c1d984)] 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 PRUint32 TIME_RELATIVE_EPOCH = 0; const PRUint32 TIME_RELATIVE_TODAY = 1; const PRUint32 TIME_RELATIVE_NOW = 2; attribute PRTime beginTime; attribute PRUint32 beginTimeReference; readonly attribute boolean hasBeginTime; readonly attribute PRTime absoluteBeginTime; attribute PRTime endTime; attribute PRUint32 endTimeReference; readonly attribute boolean hasEndTime; readonly attribute PRTime absoluteEndTime; /** * Text search terms. */ attribute AString searchTerms; readonly attribute boolean hasSearchTerms; /** * When set, returns only bookmarked items, when unset, returns anything. Setting this * is equivalent to listing all bookmark folders in the 'folders' parameter. */ attribute boolean onlyBookmarked; /** * This controls the meaning of 'domain', and whether it is an exact match * 'domainIsHost' = true, or hierarchical (= false). */ attribute boolean domainIsHost; /** * This is the host or domain name (controlled by domainIsHost). When * domainIsHost, domain only does exact matching on host names. Otherwise, * it will return anything whose host name ends in 'domain'. * * This one is a little different than most. Setting it to an empty string * is a real query and will match any URI that has no host name (local files * and such). Set this to NULL (in C++ use SetIsVoid) if you don't want * domain matching. */ attribute AUTF8String domain; readonly attribute boolean hasDomain; /** * Controls the interpretation of 'uri'. When unset (default), the URI will * request an exact match of the specified URI. When set, any history entry * beginning in 'uri' will match. For example "http://bar.com/foo" will match * "http://bar.com/foo" as well as "http://bar.com/foo/baz.gif". */ attribute boolean uriIsPrefix; /** * This is a URI to match, to, for example, find out every time you visited * a given URI. Use uriIsPrefix to control whether this is an exact match. */ attribute nsIURI uri; readonly attribute boolean hasUri; /** * Test for existance or non-existance of a given annotation. We don't * currently support >1 annotation name per query. If 'annotationIsNot' is * true, we test for the non-existance 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 (which might include bookmark folders -- use the bookmark * service's GetFolderURI) 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 in all of the given folders. */ void getFolders(out PRUint32 count, [retval,array,size_is(count)] out PRInt64 folders); readonly attribute PRUint32 folderCount; void setFolders([const,array, size_is(folderCount)] in PRInt64 folders, in PRUint32 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(25fd4de4-33b0-475e-a63d-2bcb1d123e0d)] interface nsINavHistoryQueryOptions : nsISupports { /** * Groping by exact host. The results will be an array of nsINavHistoryResults * with type = RESULT_TYPE_HOST, one for each unique host (for example, * "bugzilla.mozilla.org" and "www.mozilla.org" will be separate). The * children of these will correspond to the results for each host. */ const PRUint32 GROUP_BY_HOST = 1; /** * Grouping by toplevel domain. Similar to GROUP_BY_HOST, but there will be * one result for each toplevel domain (mozilla.org will be one entry, and * will contain results including, for example, "bugzilla.mozilla.org" and * "www.mozilla.org"). */ const PRUint32 GROUP_BY_DOMAIN = 2; /** * Group by bookmark folder. Since this determines the entire subtree * hierarchy, it must be the last grouping option given. This option * requires the query to have onlyBookmarked set, and for there to be * at least one parent folder specified via nsINavHistoryQuery::setFolders. * If all of the top-level results belong to a single folder, the folder will * be omitted and its children will become the toplevel result nodes. */ const PRUint32 GROUP_BY_FOLDER = 3; /** * 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 PRUint32 SORT_BY_NONE = 0; const PRUint32 SORT_BY_TITLE_ASCENDING = 1; const PRUint32 SORT_BY_TITLE_DESCENDING = 2; const PRUint32 SORT_BY_DATE_ASCENDING = 3; const PRUint32 SORT_BY_DATE_DESCENDING = 4; const PRUint32 SORT_BY_URI_ASCENDING = 5; const PRUint32 SORT_BY_URI_DESCENDING = 6; const PRUint32 SORT_BY_VISITCOUNT_ASCENDING = 7; const PRUint32 SORT_BY_VISITCOUNT_DESCENDING = 8; /** * "URI" results, one for each URI visited in the range. Individual result * nodes will be of type "URI". */ const PRUint32 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" */ const PRUint32 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). */ const PRUint32 RESULTS_AS_FULL_VISIT = 2; /** * The grouping mode to be used for this query. * Grouping mode is an array of GROUP_BY_* values that specifies the * structure of the tree you want. If you don't want grouping, you can * specify an empty array. */ void getGroupingMode(out PRUint32 groupCount, [retval,array,size_is(groupCount)] out PRUint32 groupingMode); void setGroupingMode([const,array,size_is(groupCount)] in PRUint32 groupingMode, in PRUint32 groupCount); /** * The sorting mode to be used for this query. * mode is one of SORT_BY_* */ attribute PRUint32 sortingMode; /** * Sets the result type. One of RESULT_TYPE_* which includes how URIs are * represented. */ attribute PRUint32 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). * Ignored for queries over history. Defaults to false. */ attribute boolean excludeItems; /** * Set to true to exclude queries ("place:" URIs) from the query results. * Simple folder queries (bookmark folder symlinks) will still be included. * Defaults to false. */ attribute boolean excludeQueries; /** * Set to true to exclude read-only folders from the query results. This is * designed for cases where you want to give the user the option of filing * something into a list of folders. It only affects cases where the actual * folder result node would appear in its parent folder and filters it out. * It doesn't affect the query at all, and doesn't affect more complex * queries (such as "folders with annotation X"). */ attribute boolean excludeReadOnlyFolders; /** * When set, allows items with "place:" URIs to appear as containers, * with the container's contents filled in from the stored query. * If not set, these will appear as normal items. Doesn't do anything if * excludeQueries is set. Defaults to false. * * Note that this has no effect on folder links, which are place: URIs * returned by nsINavBookmarkService.GetFolderURI. These are always expanded * and will appear as bookmark folders. */ attribute boolean expandQueries; /** * Normally the title of a result will be the user's custom title if there is * one, falling back on the default page title. If this is set, we will not * do this operation and always use the original page title extracted from * the HTML of the page. Defaults to false. */ attribute boolean forceOriginalTitle; /** * Most items in history are marked "hidden." Only toplevel pages that the * user sees in the URL bar are not hidden. Hidden things include the content * of iframes and all images on web pages. Normally, you don't want these * things. If you do, set this flag and you'll get all items, 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 PRUint32 maxResults; /** * Creates a new options item with the same parameters of this one. */ nsINavHistoryQueryOptions clone(); }; [scriptable, uuid(C51F54CB-5E89-4B20-A37C-1343888935B7)] interface nsINavHistoryService : nsISupports { /** * This transition type means the user followed a link and got a new toplevel * window. */ const PRUint32 TRANSITION_LINK = 1; /** * This transition type means that the user typed the page's URL in the * URL bar. */ const PRUint32 TRANSITION_TYPED = 2; /** * This transition is set when the user followed a bookmark to get to the * page. */ const PRUint32 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, regardless if whether or not the user * clicked something to get there. */ const PRUint32 TRANSITION_EMBED = 4; /** * Set when the transition was a permanent redirect. */ const PRUint32 TRANSITION_REDIRECT_PERMANENT = 5; /** * Set when the transition was a temporary redirect. */ const PRUint32 TRANSITION_REDIRECT_TEMPORARY = 6; /** * 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; /** * This sets the user-defined title of the page. Silently fails if we have * no knowledge of this page. Set to empty string to clear the user title and * only use the "real" title as declared on the page. */ void setPageUserTitle(in nsIURI aURI, in AString aUserTitle); /** * 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); /** * Returns true if this URI would be added to the history. You don't have to * worry about calling this, addPageToSession/addURI 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); /** * Call to set the full information for a given page. If the page does not * exist, it will be added to the database. If it does, the existing values * WILL BE OVERWRITTEN. This is an updated version of addPageWithDetails * for backup/restore type operations. * * @param aURI Page to add/change. * @param aTitle Title as specified by the page. * @param aUserTitle Custom title provided by user. Set to NULL if none. * @param aVisitCount Number of times this page has been visited. Setting this * to 0 may make the page invisible in some views. * @param aHidden Whether the page is hidden. If the page has only * TRANSITION_EMBED visits, this will be true, otherwise * false. * @param aTyped True if this URI has ever been typed. */ void setPageDetails(in nsIURI aURI, in AString aTitle, in AString aUserTitle, in PRUint32 aVisitCount, in boolean aHidden, in boolean aTyped); /** * Call to manually add a visit for a specific page. This will probably not * be commonly used other than for backup/restore type operations. If the URI * does not have an entry in the history database already, one will be created * with no visits, no title, hidden, not typed. Adding a visit will * automatically increment the visit count for the visited page and will unhide * it and/or mark it typed according to the transition type. * * @param aURI Visited page * @param aTime Time page was visited (microseconds) * @param aReferringVisit The ID of the visit that generated this one. Use 0 * for no referrer. This must be a valid visit already * in the DB or 0. * @param aTranstitionType Type of transition: one of TRANSITION_* above * @param aIsRedirect True if the given visit redirects to somewhere else. * (ie you will create an visit out of here that is a * redirect transition). This causes this page to be * hidden in normal history views (unless it has been * unhidden by visiting it with a non-redirect). * @param aSessionID The session ID that this page belongs to. Use 0 for * no session. * @returns The ID of the created visit. This will be 0 if the URI is not * valid for adding to history (canAddURI = false). */ PRInt64 addVisit(in nsIURI aURI, in PRTime aTime, in PRInt64 aReferringVisit, in PRInt32 aTransitionType, in boolean aIsRedirect, in PRInt64 aSessionID); /** * 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 PRUint32 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 PRUint32 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 PRUint32 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); /** * Causes observers to be notified of a beginUpdateBatch when a lot of things * are about to change. Calls can be nested, observers will only be * notified when all batches begin/end. */ void beginUpdateBatch(); /** * Causes observers to be notified of an endUpdateBatch when a batch is * done changing. Should match beginUpdateBatch or bad things will happen. */ void endUpdateBatch(); }; /** * nsIMorkHistoryImporter is a service which handles importing old * history files. */ [scriptable, uuid(be935aed-6929-4e44-be29-17ec89e5c8bd)] interface nsIMorkHistoryImporter : nsISupports { /** * Import the given Mork history file. * @param file The Mork history file to import * @param history A reference to the nsINavHistoryService. This is * supplied since the importer is invoked during * history service initialization. */ void importHistory(in nsIFile file, in nsINavHistoryService history); };