Add m-esr52 at 52.6.0

1 files changed, 697 insertions, 0 deletions

diff --git a/toolkit/components/places/nsINavBookmarksService.idl b/toolkit/components/places/nsINavBookmarksService.idl
new file mode 100644
index 000000000..e9e49a4f4
--- /dev/null
+++ b/toolkit/components/places/nsINavBookmarksService.idl
@@ -0,0 +1,697 @@
+/* -*- 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/. */
+
+#include "nsISupports.idl"
+
+interface nsIFile;
+interface nsIURI;
+interface nsITransaction;
+interface nsINavHistoryBatchCallback;
+
+/**
+ * Observer for bookmarks changes.
+ */
+[scriptable, uuid(c06b4e7d-15b1-4d4f-bdf7-147d2be9084a)]
+interface nsINavBookmarkObserver : nsISupports
+{
+  /*
+   * This observer should not be called for items that are tags.
+   */
+  readonly attribute boolean skipTags;
+
+  /*
+   * This observer should not be called for descendants when the parent is removed.
+   * For example when revmoing a folder containing bookmarks.
+   */
+  readonly attribute boolean skipDescendantsOnItemRemoval;
+
+  /**
+   * Notifies that a batch transaction has started.
+   * Other notifications will be sent during the batch, but the observer is
+   * guaranteed that onEndUpdateBatch() will be called at its completion.
+   * During a batch the observer should do its best to reduce the work done to
+   * handle notifications, since multiple changes are going to happen in a short
+   * timeframe.
+   */
+  void onBeginUpdateBatch();
+
+  /**
+   * Notifies that a batch transaction has ended.
+   */
+  void onEndUpdateBatch();
+
+  /**
+   * Notifies that an item (any type) was added.  Called after the actual
+   * addition took place.
+   * When a new item is created, all the items following it in the same folder
+   * will have their index shifted down, but no additional notifications will
+   * be sent.
+   *
+   * @param aItemId
+   *        The id of the item that was added.
+   * @param aParentId
+   *        The id of the folder to which the item was added.
+   * @param aIndex
+   *        The item's index in the folder.
+   * @param aItemType
+   *        The type of the added item (see TYPE_* constants below).
+   * @param aURI
+   *        The URI of the added item if it was TYPE_BOOKMARK, null otherwise.
+   * @param aTitle
+   *        The title of the added item.
+   * @param aDateAdded
+   *        The stored date added value, in microseconds from the epoch.
+   * @param aGuid
+   *        The unique ID associated with the item.
+   * @param aParentGuid
+   *        The unique ID associated with the item's parent.
+   * @param aSource
+   *        A change source constant from nsINavBookmarksService::SOURCE_*,
+   *        passed to the method that notifies the observer.
+   */
+  void onItemAdded(in long long aItemId,
+                   in long long aParentId,
+                   in long aIndex,
+                   in unsigned short aItemType,
+                   in nsIURI aURI,
+                   in AUTF8String aTitle,
+                   in PRTime aDateAdded,
+                   in ACString aGuid,
+                   in ACString aParentGuid,
+                   in unsigned short aSource);
+
+  /**
+   * Notifies that an item was removed.  Called after the actual remove took
+   * place.
+   * When an item is removed, all the items following it in the same folder
+   * will have their index shifted down, but no additional notifications will
+   * be sent.
+   *
+   * @param aItemId
+   *        The id of the item that was removed.
+   * @param aParentId
+   *        The id of the folder from which the item was removed.
+   * @param aIndex
+   *        The bookmark's index in the folder.
+   * @param aItemType
+   *        The type of the item to be removed (see TYPE_* constants below).
+   * @param aURI
+   *        The URI of the added item if it was TYPE_BOOKMARK, null otherwise.
+   * @param aGuid
+   *        The unique ID associated with the item.
+   * @param aParentGuid
+   *        The unique ID associated with the item's parent.
+   * @param aSource
+   *        A change source constant from nsINavBookmarksService::SOURCE_*,
+   *        passed to the method that notifies the observer.
+   */
+  void onItemRemoved(in long long aItemId,
+                     in long long aParentId,
+                     in long aIndex,
+                     in unsigned short aItemType,
+                     in nsIURI aURI,
+                     in ACString aGuid,
+                     in ACString aParentGuid,
+                     in unsigned short aSource);
+
+  /**
+   * Notifies that an item's information has changed.  This will be called
+   * whenever any attributes like "title" are changed.
+   *
+   * @param aItemId
+   *        The id of the item that was changed.
+   * @param aProperty
+   *        The property which changed.  Can be null for the removal of all of
+   *        the annotations, in this case aIsAnnotationProperty is true.
+   * @param aIsAnnotationProperty
+   *        Whether or not aProperty is the name of an annotation.  If true
+   *        aNewValue is always an empty string.
+   * @param aNewValue
+   *        For certain properties, this is set to the new value of the
+   *        property (see the list below).
+   * @param aLastModified
+   *        The updated last-modified value.
+   * @param aItemType
+   *        The type of the item to be removed (see TYPE_* constants below).
+   * @param aParentId
+   *        The id of the folder containing the item.
+   * @param aGuid
+   *        The unique ID associated with the item.
+   * @param aParentGuid
+   *        The unique ID associated with the item's parent.
+   * @param aOldValue
+   *        For certain properties, this is set to the new value of the
+   *        property (see the list below).
+   * @param aSource
+   *        A change source constant from nsINavBookmarksService::SOURCE_*,
+   *        passed to the method that notifies the observer.
+   *
+   * @note List of values that may be associated with properties:
+   *       aProperty     | aNewValue
+   *       =====================================================================
+   *       cleartime     | Empty string (all visits to this item were removed).
+   *       title         | The new title.
+   *       favicon       | The "moz-anno" URL of the new favicon.
+   *       uri           | new URL.
+   *       tags          | Empty string (tags for this item changed)
+   *       dateAdded     | PRTime (as string) when the item was first added.
+   *       lastModified  | PRTime (as string) when the item was last modified.
+   *
+   *       aProperty     | aOldValue
+   *       =====================================================================
+   *       cleartime     | Empty string (currently unused).
+   *       title         | Empty string (currently unused).
+   *       favicon       | Empty string (currently unused).
+   *       uri           | old URL.
+   *       tags          | Empty string (currently unused).
+   *       dateAdded     | Empty string (currently unused).
+   *       lastModified  | Empty string (currently unused).
+   */
+  void onItemChanged(in long long aItemId,
+                     in ACString aProperty,
+                     in boolean aIsAnnotationProperty,
+                     in AUTF8String aNewValue,
+                     in PRTime aLastModified,
+                     in unsigned short aItemType,
+                     in long long aParentId,
+                     in ACString aGuid,
+                     in ACString aParentGuid,
+                     in AUTF8String aOldValue,
+                     in unsigned short aSource);
+
+  /**
+   * Notifies that the item was visited.  Can be invoked only for TYPE_BOOKMARK
+   * items.
+   *
+   * @param aItemId
+   *        The id of the bookmark that was visited.
+   * @param aVisitId
+   *        The id of the visit.
+   * @param aTime
+   *        The time of the visit.
+   * @param aTransitionType
+   *        The transition for the visit.  See nsINavHistoryService::TRANSITION_*
+   *        constants for a list of possible values.
+   * @param aURI
+   *        The nsIURI for this bookmark.
+   * @param aParentId
+   *        The id of the folder containing the item.
+   * @param aGuid
+   *        The unique ID associated with the item.
+   * @param aParentGuid
+   *        The unique ID associated with the item's parent.
+   *
+   * @see onItemChanged with property = "cleartime" for when all visits to an
+   *      item are removed.
+   *
+   * @note The reported time is the time of the visit that was added, which may
+   *       be well in the past since the visit time can be specified.  This
+   *       means that the visit the observer is told about may not be the most
+   *       recent visit for that page.
+   */
+  void onItemVisited(in long long aItemId,
+                     in long long aVisitId,
+                     in PRTime aTime,
+                     in unsigned long aTransitionType,
+                     in nsIURI aURI,
+                     in long long aParentId,
+                     in ACString aGuid,
+                     in ACString aParentGuid);
+
+  /**
+   * Notifies that an item has been moved.
+   *
+   * @param aItemId
+   *        The id of the item that was moved.
+   * @param aOldParentId
+   *        The id of the old parent.
+   * @param aOldIndex
+   *        The old index inside the old parent.
+   * @param aNewParentId
+   *        The id of the new parent.
+   * @param aNewIndex
+   *        The index inside the new parent.
+   * @param aItemType
+   *        The type of the item to be removed (see TYPE_* constants below).
+   * @param aGuid
+   *        The unique ID associated with the item.
+   * @param aOldParentGuid
+   *        The unique ID associated with the old item's parent.
+   * @param aNewParentGuid
+   *        The unique ID associated with the new item's parent.
+   * @param aSource
+   *        A change source constant from nsINavBookmarksService::SOURCE_*,
+   *        passed to the method that notifies the observer.
+   */
+  void onItemMoved(in long long aItemId,
+                   in long long aOldParentId,
+                   in long aOldIndex,
+                   in long long aNewParentId,
+                   in long aNewIndex,
+                   in unsigned short aItemType,
+                   in ACString aGuid,
+                   in ACString aOldParentGuid,
+                   in ACString aNewParentGuid,
+                   in unsigned short aSource);
+};
+
+/**
+ * The BookmarksService interface provides methods for managing bookmarked
+ * history items.  Bookmarks consist of a set of user-customizable
+ * folders.  A URI in history can be contained in one or more such folders.
+ */
+
+[scriptable, uuid(24533891-afa6-4663-b72d-3143d03f1b04)]
+interface nsINavBookmarksService : nsISupports
+{
+  /**
+   * The item ID of the Places root.
+   */
+  readonly attribute long long placesRoot;
+
+  /**
+   * The item ID of the bookmarks menu folder.
+   */
+  readonly attribute long long bookmarksMenuFolder;
+
+  /**
+   * The item ID of the top-level folder that contain the tag "folders".
+   */
+  readonly attribute long long tagsFolder;
+
+ /**
+  * The item ID of the unfiled-bookmarks folder.
+  */
+  readonly attribute long long unfiledBookmarksFolder;
+
+  /**
+   * The item ID of the personal toolbar folder.
+   */
+  readonly attribute long long toolbarFolder;
+
+  /**
+   * The item ID of the mobile bookmarks folder.
+   */
+  readonly attribute long long mobileFolder;
+
+  /**
+   * This value should be used for APIs that allow passing in an index
+   * where an index is not known, or not required to be specified.
+   * e.g.: When appending an item to a folder.
+   */
+  const short DEFAULT_INDEX = -1;
+
+  const unsigned short TYPE_BOOKMARK = 1;
+  const unsigned short TYPE_FOLDER = 2;
+  const unsigned short TYPE_SEPARATOR = 3;
+  // Dynamic containers are deprecated and unsupported.
+  // This const exists just to avoid reusing the value.
+  const unsigned short TYPE_DYNAMIC_CONTAINER = 4;
+
+  // Change source constants. These are used to distinguish changes made by
+  // Sync and bookmarks import from other Places consumers, though they can
+  // be extended to support other callers. Sources are passed as optional
+  // parameters to methods used by Sync, and forwarded to observers.
+  const unsigned short SOURCE_DEFAULT = 0;
+  const unsigned short SOURCE_SYNC = 1;
+  const unsigned short SOURCE_IMPORT = 2;
+  const unsigned short SOURCE_IMPORT_REPLACE = 3;
+
+  /**
+   * Inserts a child bookmark into the given folder.
+   *
+   *  @param aParentId
+   *         The id of the parent folder
+   *  @param aURI
+   *         The URI to insert
+   *  @param aIndex
+   *         The index to insert at, or DEFAULT_INDEX to append
+   *  @param aTitle
+   *         The title for the new bookmark
+   *  @param [optional] aGuid
+   *         The GUID to be set for the new item.  If not set, a new GUID is
+   *         generated.  Unless you've a very sound reason, such as an undo
+   *         manager implementation, do not pass this argument.
+   *  @param [optional] aSource
+   *         The change source. This is forwarded to all bookmark observers,
+   *         allowing them to distinguish between insertions from different
+   *         callers. Defaults to SOURCE_DEFAULT if omitted.
+   *  @return The ID of the newly-created bookmark.
+   *
+   *  @note aTitle will be truncated to TITLE_LENGTH_MAX and
+   *        aURI will be truncated to URI_LENGTH_MAX.
+   *  @throws if aGuid is malformed.
+   */
+  long long insertBookmark(in long long aParentId, in nsIURI aURI,
+                           in long aIndex, in AUTF8String aTitle,
+                           [optional] in ACString aGuid,
+                           [optional] in unsigned short aSource);
+
+  /**
+   * Removes a child item. Used to delete a bookmark or separator.
+   *  @param aItemId
+   *         The child item to remove
+   *  @param [optional] aSource
+   *         The change source, forwarded to all bookmark observers. Defaults
+   *         to SOURCE_DEFAULT.
+   */
+  void removeItem(in long long aItemId, [optional] in unsigned short aSource);
+
+  /**
+   * Creates a new child folder and inserts it under the given parent.
+   *  @param aParentFolder
+   *         The id of the parent folder
+   *  @param aName
+   *         The name of the new folder
+   *  @param aIndex
+   *         The index to insert at, or DEFAULT_INDEX to append
+   *  @param [optional] aGuid
+   *         The GUID to be set for the new item.  If not set, a new GUID is
+   *         generated.  Unless you've a very sound reason, such as an undo
+   *         manager implementation, do not pass this argument.
+   *  @param [optional] aSource
+   *         The change source, forwarded to all bookmark observers. Defaults
+   *         to SOURCE_DEFAULT.
+   *  @return The ID of the newly-inserted folder.
+   *  @throws if aGuid is malformed.
+   */
+  long long createFolder(in long long aParentFolder, in AUTF8String name,
+                         in long index,
+                         [optional] in ACString aGuid,
+                         [optional] in unsigned short aSource);
+
+  /**
+   * Gets an undo-able transaction for removing a folder from the bookmarks
+   * tree.
+   *  @param aItemId
+   *         The id of the folder to remove.
+   *  @param [optional] aSource
+   *         The change source, forwarded to all bookmark observers. Defaults
+   *         to SOURCE_DEFAULT.
+   *  @return An object implementing nsITransaction that can be used to undo
+   *          or redo the action.
+   *
+   * This method exists because complex delete->undo operations rely on
+   * recreated folders to have the same ID they had before they were deleted,
+   * so that any other items deleted in different transactions can be
+   * re-inserted correctly. This provides a safe encapsulation of this
+   * functionality without exposing the ability to recreate folders with
+   * specific IDs (potentially dangerous if abused by other code!) in the
+   * public API.
+   */
+  nsITransaction getRemoveFolderTransaction(in long long aItemId,
+                                            [optional] in unsigned short aSource);
+
+  /**
+   * Convenience function for container services.  Removes
+   * all children of the given folder.
+   *  @param aItemId
+   *         The id of the folder to remove children from.
+   *  @param [optional] aSource
+   *         The change source, forwarded to all bookmark observers. Defaults
+   *         to SOURCE_DEFAULT.
+   */
+  void removeFolderChildren(in long long aItemId,
+                            [optional] in unsigned short aSource);
+
+  /**
+   * Moves an item to a different container, preserving its contents.
+   *  @param aItemId
+   *         The id of the item to move
+   *  @param aNewParentId
+   *         The id of the new parent
+   *  @param aIndex
+   *         The index under aNewParent, or DEFAULT_INDEX to append
+   *  @param [optional] aSource
+   *         The change source, forwarded to all bookmark observers. Defaults
+   *         to SOURCE_DEFAULT.
+   *
+   * NOTE: When moving down in the same container we take into account the
+   * removal of the original item. If you want to move from index X to
+   * index Y > X you must use moveItem(id, folder, Y + 1)
+   */
+  void moveItem(in long long aItemId,
+                in long long aNewParentId,
+                in long aIndex,
+                [optional] in unsigned short aSource);
+
+  /**
+   * Inserts a bookmark separator into the given folder at the given index.
+   * The separator can be removed using removeChildAt().
+   *  @param aParentId
+   *         The id of the parent folder
+   *  @param aIndex
+   *         The separator's index under folder, or DEFAULT_INDEX to append
+   *  @param [optional] aGuid
+   *         The GUID to be set for the new item.  If not set, a new GUID is
+   *         generated.  Unless you've a very sound reason, such as an undo
+   *         manager implementation, do not pass this argument.
+   *  @param [optional] aSource
+   *         The change source, forwarded to all bookmark observers. Defaults
+   *         to SOURCE_DEFAULT.
+   *  @return The ID of the new separator.
+   *  @throws if aGuid is malformed.
+   */
+  long long insertSeparator(in long long aParentId, in long aIndex,
+                            [optional] in ACString aGuid,
+                            [optional] in unsigned short aSource);
+
+  /**
+   * Get the itemId given the containing folder and the index.
+   *  @param aParentId
+   *         The id of the diret parent folder of the item
+   *  @param aIndex
+   *         The index of the item within the parent folder.
+   *         Pass DEFAULT_INDEX for the last item.
+   *  @return The ID of the found item, -1 if the item does not exists.
+   */
+  long long getIdForItemAt(in long long aParentId, in long aIndex);
+
+  /**
+   * Set the title for an item.
+   *  @param aItemId
+   *         The id of the item whose title should be updated.
+   *  @param aTitle
+   *         The new title for the bookmark.
+   *  @param [optional] aSource
+   *         The change source, forwarded to all bookmark observers. Defaults
+   *         to SOURCE_DEFAULT.
+   *
+   *  @note  aTitle will be truncated to TITLE_LENGTH_MAX.
+   */
+  void setItemTitle(in long long aItemId, in AUTF8String aTitle,
+                    [optional] in unsigned short aSource);
+
+  /**
+   * Get the title for an item.
+   *
+   * If no item title is available it will return a void string (null in JS).
+   *
+   *  @param aItemId
+   *         The id of the item whose title should be retrieved
+   *  @return The title of the item.
+   */
+  AUTF8String getItemTitle(in long long aItemId);
+
+  /**
+   * Set the date added time for an item.
+   *
+   * @param aItemId
+   *        the id of the item whose date added time should be updated.
+   * @param aDateAdded
+   *        the new date added value in microseconds.  Note that it is rounded
+   *        down to milliseconds precision.
+   *  @param [optional] aSource
+   *         The change source, forwarded to all bookmark observers. Defaults
+   *         to SOURCE_DEFAULT.
+   */
+  void setItemDateAdded(in long long aItemId,
+                        in PRTime aDateAdded,
+                        [optional] in unsigned short aSource);
+
+  /**
+   * Get the date added time for an item.
+   *
+   * @param aItemId
+   *        the id of the item whose date added time should be retrieved.
+   *
+   * @return the date added value in microseconds.
+   */
+  PRTime getItemDateAdded(in long long aItemId);
+
+  /**
+   * Set the last modified time for an item.
+   *
+   * @param aItemId
+   *        the id of the item whose last modified time should be updated.
+   * @param aLastModified
+   *        the new last modified value in microseconds.  Note that it is
+   *        rounded down to milliseconds precision.
+   * @param [optional] aSource
+   *        The change source, forwarded to all bookmark observers. Defaults
+   *        to SOURCE_DEFAULT.
+   *
+   * @note This is the only method that will send an itemChanged notification
+   *       for the property.  lastModified will still be updated in
+   *       any other method that changes an item property, but we will send
+   *       the corresponding itemChanged notification instead.
+   */
+  void setItemLastModified(in long long aItemId,
+                           in PRTime aLastModified,
+                           [optional] in unsigned short aSource);
+
+  /**
+   * Get the last modified time for an item.
+   *
+   * @param aItemId
+   *        the id of the item whose last modified time should be retrieved.
+   *
+   * @return the date added value in microseconds.
+   *
+   * @note When an item is added lastModified is set to the same value as
+   *       dateAdded.
+   */
+  PRTime getItemLastModified(in long long aItemId);
+
+  /**
+   * Get the URI for a bookmark item.
+   */
+  nsIURI getBookmarkURI(in long long aItemId);
+
+  /**
+   * Get the index for an item.
+   */
+  long getItemIndex(in long long aItemId);
+
+  /**
+   * Changes the index for a item. This method does not change the indices of
+   * any other items in the same folder, so ensure that the new index does not
+   * already exist, or change the index of other items accordingly, otherwise
+   * the indices will become corrupted.
+   *
+   * WARNING: This is API is intended for scenarios such as folder sorting,
+   *          where the caller manages the indices of *all* items in the folder.
+   *          You must always ensure each index is unique after a reordering.
+   *
+   *  @param aItemId    The id of the item to modify
+   *  @param aNewIndex  The new index
+   *  @param aSource    The optional change source, forwarded to all bookmark
+   *                    observers. Defaults to SOURCE_DEFAULT.
+   *
+   *  @throws If aNewIndex is out of bounds.
+   */
+  void setItemIndex(in long long aItemId,
+                    in long aNewIndex,
+                    [optional] in unsigned short aSource);
+
+  /**
+   * Get an item's type (bookmark, separator, folder).
+   * The type is one of the TYPE_* constants defined above.
+   */
+  unsigned short getItemType(in long long aItemId);
+
+  /**
+   * Returns true if the given URI is in any bookmark folder. If you want the
+   * results to be redirect-aware, use getBookmarkedURIFor()
+   */
+  boolean isBookmarked(in nsIURI aURI);
+
+  /**
+   * Used to see if the given URI is bookmarked, or any page that redirected to
+   * it is bookmarked. For example, if I bookmark "mozilla.org" by manually
+   * typing it in, and follow the bookmark, I will get redirected to
+   * "www.mozilla.org". Logically, this new page is also bookmarked. This
+   * function, if given "www.mozilla.org", will return the URI of the bookmark,
+   * in this case "mozilla.org".
+   *
+   * If there is no bookmarked page found, it will return NULL.
+   *
+   * @note The function will only return bookmarks in the first 2 levels of
+   *       redirection (1 -> 2 -> aURI).
+   */
+  nsIURI getBookmarkedURIFor(in nsIURI aURI);
+
+  /**
+   * Change the bookmarked URI for a bookmark.
+   * This changes which "place" the bookmark points at,
+   * which means all annotations, etc are carried along.
+   */
+  void changeBookmarkURI(in long long aItemId,
+                         in nsIURI aNewURI,
+                         [optional] in unsigned short aSource);
+
+  /**
+   * Get the parent folder's id for an item.
+   */
+  long long getFolderIdForItem(in long long aItemId);
+
+  /**
+   * Returns the list of bookmark ids that contain the given URI.
+   */
+  void getBookmarkIdsForURI(in nsIURI aURI, [optional] out unsigned long count,
+                            [array, retval, size_is(count)] out long long bookmarks);
+
+  /**
+   * Associates the given keyword with the given bookmark.
+   *
+   * Use an empty keyword to clear the keyword associated with the URI.
+   * In both of these cases, succeeds but does nothing if the URL/keyword is not found.
+   *
+   * @deprecated Use PlacesUtils.keywords.insert() API instead.
+   */
+  void setKeywordForBookmark(in long long aItemId,
+                             in AString aKeyword,
+                             [optional] in unsigned short aSource);
+
+  /**
+   * Retrieves the keyword for the given bookmark. Will be void string
+   * (null in JS) if no such keyword is found.
+   *
+   * @deprecated Use PlacesUtils.keywords.fetch() API instead.
+   */
+  AString getKeywordForBookmark(in long long aItemId);
+
+  /**
+   * Returns the URI associated with the given keyword. Empty if no such
+   * keyword is found.
+   *
+   * @deprecated Use PlacesUtils.keywords.fetch() API instead.
+   */
+  nsIURI getURIForKeyword(in AString keyword);
+
+  /**
+   * Adds a bookmark observer. If ownsWeak is false, the bookmark service will
+   * keep an owning reference to the observer.  If ownsWeak is true, then
+   * aObserver must implement nsISupportsWeakReference, and the bookmark
+   * service will keep a weak reference to the observer.
+   */
+  void addObserver(in nsINavBookmarkObserver observer, in boolean ownsWeak);
+
+  /**
+   * Removes a bookmark observer.
+   */
+  void removeObserver(in nsINavBookmarkObserver observer);
+
+  /**
+   * Gets an array of registered nsINavBookmarkObserver objects.
+   */
+  void getObservers([optional] out unsigned long count,
+                    [retval, array, size_is(count)] out nsINavBookmarkObserver observers);
+
+  /**
+   * Runs the passed callback inside of a database transaction.
+   * Use this when a lot of things are about to change, for example
+   * adding or deleting a large number of bookmark items. Calls can
+   * be nested. Observers are notified when batches begin and end, via
+   * nsINavBookmarkObserver.onBeginUpdateBatch/onEndUpdateBatch.
+   *
+   * @param aCallback
+   *        nsINavHistoryBatchCallback interface to call.
+   * @param aUserData
+   *        Opaque parameter passed to nsINavBookmarksBatchCallback
+   */
+  void runInBatchMode(in nsINavHistoryBatchCallback aCallback,
+                      in nsISupports aUserData);
+};