From 5f8de423f190bbb79a62f804151bc24824fa32d8 Mon Sep 17 00:00:00 2001 From: "Matt A. Tobin" Date: Fri, 2 Feb 2018 04:16:08 -0500 Subject: Add m-esr52 at 52.6.0 --- .../components/places/nsINavBookmarksService.idl | 697 +++++++++++++++++++++ 1 file changed, 697 insertions(+) create mode 100644 toolkit/components/places/nsINavBookmarksService.idl (limited to 'toolkit/components/places/nsINavBookmarksService.idl') 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); +}; -- cgit v1.2.3