diff options
Diffstat (limited to '')
| -rw-r--r-- | toolkit/components/places/nsINavBookmarksService.idl | 211 |
1 files changed, 211 insertions, 0 deletions
diff --git a/toolkit/components/places/nsINavBookmarksService.idl b/toolkit/components/places/nsINavBookmarksService.idl new file mode 100644 index 0000000000..1891d7c6d0 --- /dev/null +++ b/toolkit/components/places/nsINavBookmarksService.idl @@ -0,0 +1,211 @@ +/* -*- 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; + +/** + * 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 top-level folder that contain the tag "folders". + */ + readonly attribute long long tagsFolder; + + /** + * The total number of Sync changes (inserts, updates, deletes, merges, and + * uploads) recorded since Places startup for all bookmarks. + * + * Note that this is *not* the number of bookmark syncs. It's a monotonically + * increasing counter incremented for every change that affects a bookmark's + * `syncChangeCounter`. + * + * The counter can be used to avoid keeping an exclusive transaction open for + * time-consuming work. One way to do that is to store the current value of + * the counter, do the work, start a transaction, check the current value + * again, and compare it to the stored value to determine if the database + * changed during the work. + * + * The bookmarks mirror does this to check for changes between building and + * applying a merged tree. This avoids blocking the main Places connection + * during the merge, and ensures that the new tree still applies cleanly. + */ + readonly attribute long long totalSyncChanges; + + /** + * 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_SYNC_REPARENT_REMOVED_FOLDER_CHILDREN = 4; + const unsigned short SOURCE_RESTORE = 5; + const unsigned short SOURCE_RESTORE_ON_STARTUP = 6; + + /** + * Sync status flags, stored in Places for each item. These affect conflict + * resolution, when an item is changed both locally and remotely; deduping, + * when a local item matches a remote item with similar contents and different + * GUIDs; and whether we write a tombstone when an item is deleted locally. + * + * Status | Description | Conflict | Can | Needs + * | | resolution | dedupe? | tombstone? + * ----------------------------------------------------------------------- + * UNKNOWN | Automatically restored | Prefer | No | No + * | on startup to recover | deletion | | + * | from database corruption, | | | + * | or sync ID change on | | | + * | server. | | | + * ----------------------------------------------------------------------- + * NEW | Item not uploaded to | Prefer | Yes | No + * | server yet, or Sync | newer | | + * | disconnected. | | | + * ----------------------------------------------------------------------- + * NORMAL | Item uploaded to server. | Prefer | No | Yes + * | | newer | | + */ + const unsigned short SYNC_STATUS_UNKNOWN = 0; + const unsigned short SYNC_STATUS_NEW = 1; + const unsigned short SYNC_STATUS_NORMAL = 2; + + /** + * 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. + */ + [can_run_script] + 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. + */ + [can_run_script] + 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. + */ + [can_run_script] + long long createFolder(in long long aParentFolder, in AUTF8String name, + in long index, + [optional] in ACString aGuid, + [optional] in unsigned short aSource); + + /** + * 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. + */ + [can_run_script] + 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 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. + */ + [can_run_script] + void setItemLastModified(in long long aItemId, + in PRTime aLastModified, + [optional] in unsigned short aSource); +}; |