490 lines
19 KiB
Plaintext
490 lines
19 KiB
Plaintext
/* -*- 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(4d00c221-2c4a-47ab-a617-abb324110492)]
|
|
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
|
|
* =====================================================================
|
|
* guid | The new bookmark guid.
|
|
* 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
|
|
* =====================================================================
|
|
* guid | The old bookmark guid.
|
|
* 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.
|
|
* @param aURI
|
|
* The URI for this bookmark.
|
|
*/
|
|
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,
|
|
in AUTF8String aURI);
|
|
};
|
|
|
|
/**
|
|
* 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_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.
|
|
*/
|
|
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);
|
|
|
|
/**
|
|
* 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 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 parent folder's id for an item.
|
|
*/
|
|
long long getFolderIdForItem(in long long aItemId);
|
|
|
|
/**
|
|
* 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,
|
|
[optional] 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);
|
|
};
|