RetroZilla/browser/components/places/public/nsINavHistoryService.idl

/* -*- 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 <brett@gmail.com>
 *
 * 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 <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 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);
};