path: root/toolkit/components/places/nsINavHistoryService.idl

/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/**
 * Using Places services after quit-application is not reliable, so make
 * sure to do any shutdown work on quit-application, or history
 * synchronization could fail, losing latest changes.
 */

#include "nsISupports.idl"

interface nsIArray;
interface nsIFile;
interface nsIObserver;
interface nsIVariant;
interface nsIURI;

interface mozIStorageConnection;
interface mozIStorageStatementCallback;
interface mozIStoragePendingStatement;
interface nsIAsyncShutdownClient;

interface nsINavHistoryContainerResultNode;
interface nsINavHistoryQueryResultNode;
interface nsINavHistoryQuery;
interface nsINavHistoryQueryOptions;
interface nsINavHistoryResult;

[scriptable, uuid(91d104bb-17ef-404b-9f9a-d9ed8de6824c)]
interface nsINavHistoryResultNode : nsISupports
{
  /**
   * Indentifies the parent result node in the result set. This is null for
   * top level nodes.
   */
  readonly attribute nsINavHistoryContainerResultNode parent;

  /**
   * The history-result to which this node belongs.
   */
  readonly attribute nsINavHistoryResult parentResult;

  /**
   * URI of the resource in question. For visits and URLs, this is the URL of
   * the page. For folders and queries, this is the place: URI of the
   * corresponding folder or query. This may be empty for other types of
   * objects like host containers.
   */
  readonly attribute AUTF8String uri;

  /**
   * Identifies the type of this node. This node can then be QI-ed to the
   * corresponding specialized result node interface.
   */
  const unsigned long RESULT_TYPE_URI = 0;               // nsINavHistoryResultNode

  // Visit nodes are deprecated and unsupported.
  // This line exists just to avoid reusing the value:
  // const unsigned long RESULT_TYPE_VISIT = 1;

  // Full visit nodes are deprecated and unsupported.
  // This line exists just to avoid reusing the value:
  // const unsigned long RESULT_TYPE_FULL_VISIT = 2;

  // Dynamic containers are deprecated and unsupported.
  // This const exists just to avoid reusing the value:
  // const unsigned long RESULT_TYPE_DYNAMIC_CONTAINER = 4; // nsINavHistoryContainerResultNode

  const unsigned long RESULT_TYPE_QUERY = 5;             // nsINavHistoryQueryResultNode
  const unsigned long RESULT_TYPE_FOLDER = 6;            // nsINavHistoryQueryResultNode
  const unsigned long RESULT_TYPE_SEPARATOR = 7;         // nsINavHistoryResultNode
  const unsigned long RESULT_TYPE_FOLDER_SHORTCUT = 9;   // nsINavHistoryQueryResultNode
  readonly attribute unsigned long type;

  /**
   * Title of the web page, or of the node's query (day, host, folder, etc)
   */
  readonly attribute AUTF8String title;

  /**
   * Total number of times the URI has ever been accessed. For hosts, this
   * is the total of the children under it, NOT the total times the host has
   * been accessed (this would require an additional query, so is not given
   * by default when most of the time it is never needed).
   */
  readonly attribute unsigned long accessCount;

  /**
   * This is the time the user accessed the page.
   *
   * If this is a visit, it is the exact time that the page visit occurred.
   *
   * If this is a URI, it is the most recent time that the URI was visited.
   * Even if you ask for all URIs for a given date range long ago, this might
   * contain today's date if the URI was visited today.
   *
   * For hosts, or other node types with children, this is the most recent
   * access time for any of the children.
   *
   * For days queries this is the respective endTime - a maximum possible
   * visit time to fit in the day range.
   */
  readonly attribute PRTime time;

  /**
   * This URI can be used as an image source URI and will give you the favicon
   * for the page. It is *not* the URI of the favicon, but rather something
   * that will resolve to the actual image.
   *
   * In most cases, this is an annotation URI that will query the favicon
   * service. If the entry has no favicon, this is the chrome URI of the
   * default favicon. If the favicon originally lived in chrome, this will
   * be the original chrome URI of the icon.
   */
  readonly attribute AUTF8String icon;

  /**
   * This is the number of levels between this node and the top of the
   * hierarchy. The members of result.children have indentLevel = 0, their
   * children have indentLevel = 1, etc. The indent level of the root node is
   * set to -1.
   */
  readonly attribute long indentLevel;

  /**
   * When this item is in a bookmark folder (parent is of type folder), this is
   * the index into that folder of this node. These indices start at 0 and
   * increase in the order that they appear in the bookmark folder. For items
   * that are not in a bookmark folder, this value is -1.
   */
  readonly attribute long bookmarkIndex;

  /**
   * If the node is an item (bookmark, folder or a separator) this value is the
   * row ID of that bookmark in the database. For other nodes, this value is
   * set to -1.
   */
  readonly attribute long long itemId;

  /**
   * If the node is an item (bookmark, folder or a separator) this value is the
   * time that the item was created. For other nodes, this value is 0.
   */
  readonly attribute PRTime dateAdded;

  /**
   * If the node is an item (bookmark, folder or a separator) this value is the
   * time that the item was last modified. For other nodes, this value is 0.
   *
   *  @note When an item is added lastModified is set to the same value as
   *        dateAdded.
   */
  readonly attribute PRTime lastModified;

  /**
   * For uri nodes, this is a sorted list of the tags, delimited with commans,
   * for the uri represented by this node. Otherwise this is an empty string.
   */
  readonly attribute AString tags;

  /**
   * The unique ID associated with the page. It my return an empty string
   * if the result node is a non-URI node.
   */
  readonly attribute ACString pageGuid;

  /**
   * The unique ID associated with the bookmark. It returns an empty string
   * if the result node is not associated with a bookmark, a folder or a
   * separator.
   */
  readonly attribute ACString bookmarkGuid;

  /**
   * The unique ID associated with the history visit. For node types other than
   * history visit nodes, this value is -1.
   */
  readonly attribute long long visitId;

  /**
   * The transition type associated with this visit. For node types other than
   * history visit nodes, this value is 0.
   */
  readonly attribute unsigned long visitType;
};


/**
 * Base class for container results. This includes all types of groupings.
 * Bookmark folders and places queries will be QueryResultNodes which extends
 * these items.
 */
[scriptable, uuid(3E9CC95F-0D93-45F1-894F-908EEB9866D7)]
interface nsINavHistoryContainerResultNode : nsINavHistoryResultNode
{

  /**
   * Set this to allow descent into the container. When closed, attempting
   * to call getChildren or childCount will result in an error. You should
   * set this to false when you are done reading.
   *
   * For HOST and DAY groupings, doing this is free since the children have
   * been precomputed. For queries and bookmark folders, being open means they
   * will keep themselves up-to-date by listening for updates and re-querying
   * as needed.
   */
  attribute boolean containerOpen;

  /**
   * Indicates whether the container is closed, loading, or opened.  Loading
   * implies that the container has been opened asynchronously and has not yet
   * fully opened.
   */
  readonly attribute unsigned short state;
  const unsigned short STATE_CLOSED = 0;
  const unsigned short STATE_LOADING = 1;
  const unsigned short STATE_OPENED = 2;

  /**
   * This indicates whether this node "may" have children, and can be used
   * when the container is open or closed. When the container is closed, it
   * will give you an exact answer if the node can easily be populated (for
   * example, a bookmark folder). If not (for example, a complex history query),
   * it will return true. When the container is open, it will always be
   * accurate. It is intended to be used to see if we should draw the "+" next
   * to a tree item.
   */
  readonly attribute boolean hasChildren;

  /**
   * This gives you the children of the nodes. It is preferrable to use this
   * interface over the array one, since it avoids creating an nsIArray object
   * and the interface is already the correct type.
   *
   * @throws NS_ERROR_NOT_AVAILABLE if containerOpen is false.
   */
  readonly attribute unsigned long childCount;
  nsINavHistoryResultNode getChild(in unsigned long aIndex);

  /**
   * Get the index of a direct child in this container.
   *
   * @param aNode
   *        a result node.
   *
   * @return aNode's index in this container.
   * @throws NS_ERROR_NOT_AVAILABLE if containerOpen is false.
   * @throws NS_ERROR_INVALID_ARG if aNode isn't a direct child of this
   * container.
   */
  unsigned long getChildIndex(in nsINavHistoryResultNode aNode);
};


/**
 * Used for places queries and as a base for bookmark folders.
 *
 * Note that if you request places to *not* be expanded in the options that
 * generated this node, this item will report it has no children and never try
 * to populate itself.
 */
[scriptable, uuid(62817759-4FEE-44A3-B58C-3E2F5AFC9D0A)]
interface nsINavHistoryQueryResultNode : nsINavHistoryContainerResultNode
{
  /**
   * Get the query which builds this node's children.
   * Only valid for RESULT_TYPE_QUERY nodes.
   */
  readonly attribute nsINavHistoryQuery query;

  /**
   * Get the options which group this node's children.
   * Only valid for RESULT_TYPE_QUERY nodes.
   */
  readonly attribute nsINavHistoryQueryOptions queryOptions;

  /**
   * For both simple folder queries and folder shortcut queries, this is set to
   * the concrete itemId of the folder (i.e. for folder shortcuts it's the
   * target folder id).  Otherwise, this is set to -1.
   */
  readonly attribute long long folderItemId;

  /**
   * For both simple folder queries and folder shortcut queries, this is set to
   * the concrete guid of the folder (i.e. for folder shortcuts it's the target
   * folder guid). Otherwise, this is set to an empty string.
   */
  readonly attribute ACString targetFolderGuid;
};


/**
 * Allows clients to observe what is happening to a result as it updates itself
 * according to history and bookmark system events. Register this observer on a
 * result using nsINavHistoryResult::addObserver.
 */
[scriptable, uuid(f62d8b6b-3c4e-4a9f-a897-db605d0b7a0f)]
interface nsINavHistoryResultObserver : nsISupports
{
  /**
   * Whether the observer is interested into history details changes.
   * Those include visits additions and removals. If the observer doesn't
   * provide this attribute, it will default to false.
   * In practice, the observer won't receive nodeHistoryDetailsChanged.
   * Note: this is only read when the observer is added, it cannot be changed
   * dynamically.
   */
  readonly attribute boolean skipHistoryDetailsNotifications;

  /**
   * Called when 'aItem' is inserted into 'aParent' at index 'aNewIndex'.
   * The item previously at index (if any) and everything below it will have
   * been shifted down by one. The item may be a container or a leaf.
   */
  void nodeInserted(in nsINavHistoryContainerResultNode aParent,
                    in nsINavHistoryResultNode aNode,
                    in unsigned long aNewIndex);

  /**
   * Called whan 'aItem' is removed from 'aParent' at 'aOldIndex'. The item
   * may be a container or a leaf. This function will be called after the item
   * has been removed from its parent list, but before anything else (including
   * NULLing out the item's parent) has happened.
   */
  void nodeRemoved(in nsINavHistoryContainerResultNode aParent,
                   in nsINavHistoryResultNode aItem,
                   in unsigned long aOldIndex);

  /**
   * Called whan 'aItem' is moved from 'aOldParent' at 'aOldIndex' to
   * aNewParent at aNewIndex. The item may be a container or a leaf.
   *
   * XXX: at the moment, this method is called only when an item is moved
   * within the same container. When an item is moved between containers,
   * a new node is created for the item, and the itemRemoved/itemAdded methods
   * are used.
   */
  void nodeMoved(in nsINavHistoryResultNode aNode,
                 in nsINavHistoryContainerResultNode aOldParent,
                 in unsigned long aOldIndex,
                 in nsINavHistoryContainerResultNode aNewParent,
                 in unsigned long aNewIndex);

  /**
   * Called right after aNode's title has changed.
   *
   * @param aNode
   *        a result node
   * @param aNewTitle
   *        the new title
   */
  void nodeTitleChanged(in nsINavHistoryResultNode aNode,
                        in AUTF8String aNewTitle);

  /**
   * Called right after aNode's uri property has changed.
   *
   * @param aNode
   *        a result node
   * @param aNewURI
   *        the old uri
   */
  void nodeURIChanged(in nsINavHistoryResultNode aNode,
                      in AUTF8String aOldURI);

  /**
   * Called right after aNode's icon property has changed.
   *
   * @param aNode
   *        a result node
   *
   * @note: The new icon is accessible through aNode.icon.
   */
  void nodeIconChanged(in nsINavHistoryResultNode aNode);

  /**
   * Called right after aNode's time property or accessCount property, or both,
   * have changed.
   *
   * @param aNode
   *        a uri result node
   * @param aOldVisitDate
   *        the old visit date
   * @param aOldAccessCount
   *        the old access-count
   */
  void nodeHistoryDetailsChanged(in nsINavHistoryResultNode aNode,
                                 in PRTime aOldVisitDate,
                                 in unsigned long aOldAccessCount);

  /**
   * Called when the tags set on the uri represented by aNode have changed.
   *
   * @param aNode
   *        a uri result node
   *
   * @note: The new tags list is accessible through aNode.tags.
   */
  void nodeTagsChanged(in nsINavHistoryResultNode aNode);

  /**
   * Called right after the aNode's keyword property has changed.
   *
   * @param aNode
   *        a uri result node
   * @param aNewKeyword
   *        the new keyword
   */
  void nodeKeywordChanged(in nsINavHistoryResultNode aNode,
                          in AUTF8String aNewKeyword);

  /**
   * Called right after aNode's dateAdded property has changed.
   *
   * @param aNode
   *        a result node
   * @param aNewValue
   *        the new value of the dateAdded property
   */
  void nodeDateAddedChanged(in nsINavHistoryResultNode aNode,
                            in PRTime aNewValue);

  /**
   * Called right after aNode's dateModified property has changed.
   *
   * @param aNode
   *        a result node
   * @param aNewValue
   *        the new value of the dateModified property
   */
  void nodeLastModifiedChanged(in nsINavHistoryResultNode aNode,
                               in PRTime aNewValue);

  /**
   * Called after a container changes state.
   *
   * @param aContainerNode
   *        The container that has changed state.
   * @param aOldState
   *        The state that aContainerNode has transitioned out of.
   * @param aNewState
   *        The state that aContainerNode has transitioned into.
   */
  void containerStateChanged(in nsINavHistoryContainerResultNode aContainerNode,
                             in unsigned long aOldState,
                             in unsigned long aNewState);

  /**
   * Called when something significant has happened within the container. The
   * contents of the container should be re-built.
   *
   * @param aContainerNode
   *        the container node to invalidate
   */
  void invalidateContainer(in nsINavHistoryContainerResultNode aContainerNode);

  /**
   * This is called to indicate to the UI that the sort has changed to the
   * given mode. For trees, for example, this would update the column headers
   * to reflect the sorting. For many other types of views, this won't be
   * applicable.
   *
   * @param sortingMode  One of nsINavHistoryQueryOptions.SORT_BY_* that
   *                     indicates the new sorting mode.
   *
   * This only is expected to update the sorting UI. invalidateAll() will also
   * get called if the sorting changes to update everything.
   */
  void sortingChanged(in unsigned short sortingMode);

  /**
   * This is called to indicate that a batch operation is about to start or end.
   * The observer could want to disable some events or updates during batches,
   * since multiple operations are packed in a short time.
   * For example treeviews could temporarily suppress select notifications.
   *
   * @param aToggleMode
   *        true if a batch is starting, false if it's ending.
   */
  void batching(in boolean aToggleMode);

  /**
   * Called by the result when this observer is added.
   */
  attribute nsINavHistoryResult result;
};


/**
 * The result of a history/bookmark query.
 */
[scriptable, uuid(c2229ce3-2159-4001-859c-7013c52f7619)]
interface nsINavHistoryResult : nsISupports
{
  /**
   * Sorts all nodes recursively by the given parameter, one of
   * nsINavHistoryQueryOptions.SORT_BY_*  This will update the corresponding
   * options for this result, so that re-using the current options/queries will
   * always give you the current view.
   */
  attribute unsigned short sortingMode;

  /**
   * Whether or not notifications on result changes are suppressed.
   * Initially set to false.
   *
   * Use this to avoid flickering and to improve performance when you
   * do temporary changes to the result structure (e.g. when searching for a
   * node recursively).
   */
  attribute boolean suppressNotifications;

  /**
   * Adds an observer for changes done in the result.
   *
   * @param aObserver
   *        a result observer.
   * @param aOwnsWeak
   *        If false, the result will keep an owning reference to the observer,
   *        which must be removed using removeObserver.
   *        If true, the result will keep a weak reference to the observer, which
   *        must implement nsISupportsWeakReference.
   *
   * @see nsINavHistoryResultObserver
   */
  void addObserver(in nsINavHistoryResultObserver aObserver,
                   [optional] in boolean aOwnsWeak);

  /**
   * Removes an observer that was added by addObserver.
   *
   * @param aObserver
   *        a result observer that was added by addObserver.
   */
  void removeObserver(in nsINavHistoryResultObserver aObserver);

  /**
   * This is the root of the results. Remember that you need to open all
   * containers for their contents to be valid.
   *
   * When a result goes out of scope it will continue to observe changes till
   * it is cycle collected.  While the result waits to be collected it will stay
   * in memory, and continue to update itself, potentially causing unwanted
   * additional work.  When you close the root node the result will stop
   * observing changes, so it is good practice to close the root node when you
   * are done with a result, since that will avoid unwanted performance hits.
   */
  readonly attribute nsINavHistoryContainerResultNode root;

  /**
   * 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();
};


/**
 * This object encapsulates all the query parameters you're likely to need
 * when building up history UI. All parameters are ANDed together.
 *
 * This is not intended to be a super-general query mechanism. This was designed
 * so that most queries can be done in only one SQL query. This is important
 * because, if the user has their profile on a networked drive, query latency
 * can be non-negligible.
 */

[scriptable, uuid(dc87ae79-22f1-4dcf-975b-852b01d210cb)]
interface nsINavHistoryQuery : nsISupports
{
  /**
   * Time range for results (INCLUSIVE). The *TimeReference is one of the
   * constants TIME_RELATIVE_* which indicates how to interpret the
   * corresponding time value.
   *   TIME_RELATIVE_EPOCH (default):
   *     The time is relative to Jan 1 1970 GMT, (this is a normal PRTime)
   *   TIME_RELATIVE_TODAY:
   *     The time is relative to this morning at midnight. Normally used for
   *     queries relative to today. For example, a "past week" query would be
   *     today-6 days -> today+1 day
   *   TIME_RELATIVE_NOW:
   *     The time is relative to right now.
   *
   * Note: PRTime is in MICROseconds since 1 Jan 1970. Javascript date objects
   * are expressed in MILLIseconds since 1 Jan 1970.
   *
   * As a special case, a 0 time relative to TIME_RELATIVE_EPOCH indicates that
   * the time is not part of the query. This is the default, so an empty query
   * will match any time. The has* functions return whether the corresponding
   * time is considered.
   *
   * You can read absolute*Time to get the time value that the currently loaded
   * reference points + offset resolve to.
   */
  const unsigned long TIME_RELATIVE_EPOCH = 0;
  const unsigned long TIME_RELATIVE_TODAY = 1;
  const unsigned long TIME_RELATIVE_NOW = 2;

  attribute PRTime beginTime;
  attribute unsigned long beginTimeReference;
  readonly attribute boolean hasBeginTime;
  readonly attribute PRTime absoluteBeginTime;

  attribute PRTime endTime;
  attribute unsigned long endTimeReference;
  readonly attribute boolean hasEndTime;
  readonly attribute PRTime absoluteEndTime;

  /**
   * Text search terms.
   */
  attribute AString searchTerms;
  readonly attribute boolean hasSearchTerms;

  /**
   * Set lower or upper limits for how many times an item has been
   * visited.  The default is -1, and in that case all items are
   * matched regardless of their visit count.
   */
  attribute long minVisits;
  attribute long maxVisits;

  /**
   * When the set of transitions is nonempty, results are limited to pages which
   * have at least one visit for each of the transition types.
   * @note: For searching on more than one transition this can be very slow.
   *
   * Limit results to the specified list of transition types.
   */
  void setTransitions(in Array<unsigned long> transitions);

  /**
   * Get the transitions set for this query.
   */
  Array<unsigned long> getTransitions();

  /**
   * Get the count of the set query transitions.
   */
  readonly attribute unsigned long transitionCount;

  /**
   * This controls the meaning of 'domain', and whether it is an exact match
   * 'domainIsHost' = true, or hierarchical (= false).
   */
  attribute boolean domainIsHost;

  /**
   * This is the host or domain name (controlled by domainIsHost). When
   * domainIsHost, domain only does exact matching on host names. Otherwise,
   * it will return anything whose host name ends in 'domain'.
   *
   * This one is a little different than most. Setting it to an empty string
   * is a real query and will match any URI that has no host name (local files
   * and such). Set this to NULL (in C++ use SetIsVoid) if you don't want
   * domain matching.
   */
  attribute AUTF8String domain;
  readonly attribute boolean hasDomain;

  /**
   * This is a URI to match, to, for example, find out every time you visited
   * a given URI. This is an exact match.
   */
  attribute nsIURI uri;
  readonly attribute boolean hasUri;

  /**
   * Limit results to items that are tagged with all of the given tags.  This
   * attribute must be set to an array of strings.  When called as a getter it
   * will return an array of strings sorted ascending in lexicographical order.
   * The array may be empty in either case.  Duplicate tags may be specified
   * when setting the attribute, but the getter returns only unique tags.
   */
  attribute nsIVariant tags;

  /**
   * If 'tagsAreNot' is true, the results are instead limited to items that
   * are not tagged with any of the given tags.  This attribute is used in
   * conjunction with the 'tags' attribute.
   */
  attribute boolean tagsAreNot;

  /**
   * Limit results to items that are in all of the given folders.
   */
  Array<ACString> getParents();
  readonly attribute unsigned long parentCount;

  /**
   * This is not recursive so results will be returned from the first level of
   * that folder.
   */
  void setParents(in Array<ACString> aGuids);

  /**
   * Creates a new query item with the same parameters of this one.
   */
  nsINavHistoryQuery clone();
};

/**
 * This object represents the global options for executing a query.
 */
[scriptable, uuid(8198dfa7-8061-4766-95cb-fa86b3c00a47)]
interface nsINavHistoryQueryOptions : nsISupports
{
  /**
   * You can ask for the results to be pre-sorted. Since the DB has indices
   * of many items, it can produce sorted results almost for free. These should
   * be self-explanatory.
   *
   * Note: re-sorting is slower, as is sorting by title or when you have a
   * host name.
   *
   * For bookmark items, SORT_BY_NONE means sort by the natural bookmark order.
   */
  const unsigned short SORT_BY_NONE = 0;
  const unsigned short SORT_BY_TITLE_ASCENDING = 1;
  const unsigned short SORT_BY_TITLE_DESCENDING = 2;
  const unsigned short SORT_BY_DATE_ASCENDING = 3;
  const unsigned short SORT_BY_DATE_DESCENDING = 4;
  const unsigned short SORT_BY_URI_ASCENDING = 5;
  const unsigned short SORT_BY_URI_DESCENDING = 6;
  const unsigned short SORT_BY_VISITCOUNT_ASCENDING = 7;
  const unsigned short SORT_BY_VISITCOUNT_DESCENDING = 8;
  const unsigned short SORT_BY_DATEADDED_ASCENDING = 11;
  const unsigned short SORT_BY_DATEADDED_DESCENDING = 12;
  const unsigned short SORT_BY_LASTMODIFIED_ASCENDING = 13;
  const unsigned short SORT_BY_LASTMODIFIED_DESCENDING = 14;
  const unsigned short SORT_BY_TAGS_ASCENDING = 17;
  const unsigned short SORT_BY_TAGS_DESCENDING = 18;
  const unsigned short SORT_BY_FRECENCY_ASCENDING = 21;
  const unsigned short SORT_BY_FRECENCY_DESCENDING = 22;

  /**
   * "URI" results, one for each URI visited in the range. Individual result
   * nodes will be of type "URI".
   */
  const unsigned short RESULTS_AS_URI = 0;

  /**
   * "Visit" results, with one for each time a page was visited (this will
   * often give you multiple results for one URI). Individual result nodes will
   * have type "Visit"
   *
   * @note This result type is only supported by QUERY_TYPE_HISTORY.
   */
  const unsigned short RESULTS_AS_VISIT = 1;

  /**
   * This returns query nodes for each predefined date range where we
   * had visits. The node contains information how to load its content:
   * - visits for the given date range will be loaded.
   *
   * @note This result type is only supported by QUERY_TYPE_HISTORY.
   */
  const unsigned short RESULTS_AS_DATE_QUERY = 3;

  /**
   * This returns nsINavHistoryQueryResultNode nodes for each site where we
   * have visits. The node contains information how to load its content:
   * - last visit for each url in the given host will be loaded.
   *
   * @note This result type is only supported by QUERY_TYPE_HISTORY.
   */
  const unsigned short RESULTS_AS_SITE_QUERY = 4;

  /**
   * This returns nsINavHistoryQueryResultNode nodes for each day where we
   * have visits. The node contains information how to load its content:
   * - list of hosts visited in the given period will be loaded.
   *
   * @note This result type is only supported by QUERY_TYPE_HISTORY.
   */
  const unsigned short RESULTS_AS_DATE_SITE_QUERY = 5;

  /**
   * This returns nsINavHistoryQueryResultNode nodes for each tag.
   * The node contains information how to load its content:
   * - list of bookmarks with the given tag will be loaded.
   *
   * @note Setting this resultType will force queryType to QUERY_TYPE_BOOKMARKS.
   */
  const unsigned short RESULTS_AS_TAGS_ROOT = 6;

  /**
   * DEPRECATED: This exists for Sync and also to avoid reusing this number.
   */
  const unsigned short RESULTS_AS_TAG_CONTENTS = 7;

  /**
   * This returns nsINavHistoryQueryResultNode nodes for each top-level bookmark
   * root.
   *
   * @note Setting this resultType will force queryType to QUERY_TYPE_BOOKMARKS.
   */
  const unsigned short RESULTS_AS_ROOTS_QUERY = 8;

  /**
   * This returns nsINavHistoryQueryResultNode for each left-pane root.
   */
  const unsigned short RESULTS_AS_LEFT_PANE_QUERY = 9;

  /**
   * The sorting mode to be used for this query.
   * mode is one of SORT_BY_*
   */
  attribute unsigned short sortingMode;

  /**
   * Sets the result type. One of RESULT_TYPE_* which includes how URIs are
   * represented.
   */
  attribute unsigned short resultType;

  /**
   * This option excludes all URIs and separators from a bookmarks query.
   * This would be used if you just wanted a list of bookmark folders and
   * queries (such as the left pane of the places page).
   * Defaults to false.
   */
  attribute boolean excludeItems;

  /**
   * Set to true to exclude queries ("place:" URIs) from the query results.
   * Simple folder queries (bookmark folder symlinks) will still be included.
   * Defaults to false.
   */
  attribute boolean excludeQueries;

  /**
   * When set, allows items with "place:" URIs to appear as containers,
   * with the container's contents filled in from the stored query.
   * If not set, these will appear as normal items. Doesn't do anything if
   * excludeQueries is set. Defaults to false.
   *
   * Note that this has no effect on folder links, which are place: URIs
   * returned by nsINavBookmarkService.GetFolderURI. These are always expanded
   * and will appear as bookmark folders.
   */
  attribute boolean expandQueries;

  /**
   * Some pages in history are marked "hidden" and thus don't appear by default
   * in queries.  These include automatic framed visits and redirects.  Setting
   * this attribute will return all pages, even hidden ones.  Does nothing for
   * bookmark queries. Defaults to false.
   */
  attribute boolean includeHidden;

  /**
   * This is the maximum number of results that you want. The query is executed,
   * the results are sorted, and then the top 'maxResults' results are taken
   * and returned. Set to 0 (the default) to get all results.
   *
   * THIS DOES NOT WORK IN CONJUNCTION WITH SORTING BY TITLE. This is because
   * sorting by title requires us to sort after using locale-sensetive sorting
   * (as opposed to letting the database do it for us).
   *
   * Instead, we get the result ordered by date, pick the maxResult most recent
   * ones, and THEN sort by title.
   */
  attribute unsigned long maxResults;

  const unsigned short QUERY_TYPE_HISTORY = 0;
  const unsigned short QUERY_TYPE_BOOKMARKS = 1;

  /**
   * The type of search to use when querying the DB; This attribute is only
   * honored by query nodes. It is silently ignored for simple folder queries.
   */
  attribute unsigned short queryType;

  /**
   * When this is true, the root container node generated by these options and
   * its descendant containers will be opened asynchronously if they support it.
   * This is false by default.
   *
   * @note Currently only bookmark folder containers support being opened
   *       asynchronously.
   */
  attribute boolean asyncEnabled;

  /**
   * Creates a new options item with the same parameters of this one.
   */
  nsINavHistoryQueryOptions clone();
};

[scriptable, uuid(20c974ff-ee16-4828-9326-1b7c9e036622)]
interface nsINavHistoryService : nsISupports
{
  // The current database schema version.
  // To migrate to a new version bump this, add a MigrateVXXUp function to
  // Database.cpp/h, and a test into tests/migration/
  const unsigned long DATABASE_SCHEMA_VERSION = 77;

  /**
   * System Notifications:
   *
   * places-init-complete - Sent once the History service is completely
   *                        initialized successfully.
   * places-database-locked - Sent if initialization of the History service
   *                          failed due to the inability to open the places.sqlite
   *                          for access reasons.
   */

  /**
   * This transition type means the user followed a link and got a new toplevel
   * window.
   */
  const unsigned long TRANSITION_LINK = 1;

  /**
   * This transition type means that the user typed the page's URL in the
   * URL bar or selected it from URL bar autocomplete results, clicked on
   * it from a history query (from the History sidebar, History menu,
   * or history query in the personal toolbar or Places organizer.
   */
  const unsigned long TRANSITION_TYPED = 2;

  /**
   * This transition is set when the user followed a bookmark to get to the
   * page.
   */
  const unsigned long TRANSITION_BOOKMARK = 3;

  /**
   * This transition type is set when some inner content is loaded. This is
   * true of all images on a page, and the contents of the iframe. It is also
   * true of any content in a frame if the user did not explicitly follow
   * a link to get there.
   */
  const unsigned long TRANSITION_EMBED = 4;

  /**
   * Set when the transition was a permanent redirect.
   */
  const unsigned long TRANSITION_REDIRECT_PERMANENT = 5;

  /**
   * Set when the transition was a temporary redirect.
   */
  const unsigned long TRANSITION_REDIRECT_TEMPORARY = 6;

  /**
   * Set when the transition is a download.
   */
  const unsigned long TRANSITION_DOWNLOAD = 7;

  /**
   * This transition type means the user followed a link and got a visit in
   * a frame.
   */
  const unsigned long TRANSITION_FRAMED_LINK = 8;

  /**
   * This transition type means the page has been reloaded.
   */
  const unsigned long TRANSITION_RELOAD = 9;

  /**
   * Set when database is coherent
   */
  const unsigned short DATABASE_STATUS_OK = 0;

  /**
   * Set when database did not exist and we created a new one.
   */
  const unsigned short DATABASE_STATUS_CREATE = 1;

  /**
   * Set when database was corrupt and we replaced it with a new one.
   */
  const unsigned short DATABASE_STATUS_CORRUPT = 2;

  /**
   * Set when database schema has been upgraded.
   */
  const unsigned short DATABASE_STATUS_UPGRADED = 3;

  /**
   * Set when database couldn't be opened.
   */
  const unsigned short DATABASE_STATUS_LOCKED = 4;

  /**
   * Insert this value into moz_historyvisits if the visit source is organic.
   */
  const unsigned short VISIT_SOURCE_ORGANIC = 0;

  /**
   * Insert this value into moz_historyvisits if the visit source is sponsored.
   */
  const unsigned short VISIT_SOURCE_SPONSORED = 1;

  /**
   * Insert this value into moz_historyvisits if the visit source is bookmarked.
   */
  const unsigned short VISIT_SOURCE_BOOKMARKED = 2;

  /**
   * Insert this value into moz_historyvisits if the visit source is searched.
   */
  const unsigned short VISIT_SOURCE_SEARCHED = 3;

  /**
   * Returns the current database status
   */
  readonly attribute unsigned short databaseStatus;

  /**
   * This is just like markPageAsTyped (in nsIBrowserHistory, also implemented
   * by the history service), but for bookmarks. It declares that the given URI
   * is being opened as a result of following a bookmark. If this URI is loaded
   * soon after this message has been received, that transition will be marked
   * as following a bookmark.
   */
  void markPageAsFollowedBookmark(in nsIURI aURI);

  /**
   * Designates the url as having been explicitly typed in by the user.
   *
   * @param aURI
   *        URI of the page to be marked.
   */
  void markPageAsTyped(in nsIURI aURI);

  /**
   * Designates the url as coming from a link explicitly followed by
   * the user (for example by clicking on it).
   *
   * @param aURI
   *        URI of the page to be marked.
   */
  void markPageAsFollowedLink(in nsIURI aURI);

  /**
   * Returns true if this URI would be added to the history. You don't have to
   * worry about calling this, adding a visit will always check before
   * actually adding the page. This function is public because some components
   * may want to check if this page would go in the history (i.e. for
   * annotations).
   */
  boolean canAddURI(in nsIURI aURI);

  /**
   * This returns a new query object that you can pass to executeQuer[y/ies].
   * It will be initialized to all empty (so using it will give you all history).
   */
  nsINavHistoryQuery getNewQuery();

  /**
   * This returns a new options object that you can pass to executeQuer[y/ies]
   * after setting the desired options.
   */
  nsINavHistoryQueryOptions getNewQueryOptions();

  /**
   * Executes a single query.
   */
  nsINavHistoryResult executeQuery(in nsINavHistoryQuery aQuery,
                                   in nsINavHistoryQueryOptions options);

  /**
   * Converts a query URI-like string to a query object.
   */
  void queryStringToQuery(in AUTF8String aQueryString,
                          out nsINavHistoryQuery aQuery,
                          out nsINavHistoryQueryOptions options);

  /**
   * Converts a query into an equivalent string that can be persisted. Inverse
   * of queryStringToQuery()
   */
  AUTF8String queryToQueryString(in nsINavHistoryQuery aQuery,
                                 in nsINavHistoryQueryOptions options);

  /**
   * True if history is disabled. currently,
   * history is disabled if the places.history.enabled pref is false.
   */
  readonly attribute boolean historyDisabled;

  /**
   * Generate a guid.
   * Guids can be used for any places purposes (history, bookmarks, etc.)
   * Returns null if the generation of the guid failed.
   */
  ACString makeGuid();

  /**
   * Returns a 48-bit hash for a URI spec.
   *
   * @param aSpec
   *        The URI spec to hash.
   * @param aMode
   *        The hash mode: `""` (default), `"prefix_lo"`, or `"prefix_hi"`.
   */
  unsigned long long hashURL(in ACString aSpec, [optional] in ACString aMode);

  /**
   * Whether frecency is in the process of being decayed. The value can also
   * be read through the is_frecency_decaying() SQL function exposed by Places
   * database connections.
   */
  attribute boolean isFrecencyDecaying;

  /**
   * This is set to true when a frecency is invalidated and set back to false
   * when all the outdated values have been recalculated.
   */
  attribute boolean shouldStartFrecencyRecalculation;

  /**
   * The database connection used by Places.
   */
  readonly attribute mozIStorageConnection DBConnection;

  /**
   * Asynchronously executes the statement created from a query.
   *
   * @see nsINavHistoryService::executeQuery
   * @note THIS IS A TEMPORARY API.  Don't rely on it, since it will be replaced
   *       in future versions by a real async querying API.
   * @note Results obtained from this method differ from results obtained from
   *       executeQuery, because there is additional filtering and sorting
   *       done by the latter.  Thus you should use executeQuery, unless you
   *       are absolutely sure that the returned results are fine for
   *       your use-case.
   */
  mozIStoragePendingStatement asyncExecuteLegacyQuery(
    in nsINavHistoryQuery aQuery,
    in nsINavHistoryQueryOptions aOptions,
    in mozIStorageStatementCallback aCallback);

  /**
   * Hook for clients who need to perform actions during/by the end of
   * the shutdown of the database.
   * May be null if it's too late to get one.
   */
  readonly attribute nsIAsyncShutdownClient shutdownClient;

  /**
   * Hook for internal clients who need to perform actions just before the
   * connection gets closed.
   * May be null if it's too late to get one.
   */
  readonly attribute nsIAsyncShutdownClient connectionShutdownClient;
};