michael@0: /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "nsISupports.idl" michael@0: michael@0: interface nsIFile; michael@0: interface nsIURI; michael@0: interface nsITransaction; michael@0: interface nsINavHistoryBatchCallback; michael@0: michael@0: /** michael@0: * Observer for bookmarks changes. michael@0: */ michael@0: [scriptable, uuid(8ab925f8-af9b-4837-afa0-ffed507212ce)] michael@0: interface nsINavBookmarkObserver : nsISupports michael@0: { michael@0: /** michael@0: * Notifies that a batch transaction has started. michael@0: * Other notifications will be sent during the batch, but the observer is michael@0: * guaranteed that onEndUpdateBatch() will be called at its completion. michael@0: * During a batch the observer should do its best to reduce the work done to michael@0: * handle notifications, since multiple changes are going to happen in a short michael@0: * timeframe. michael@0: */ michael@0: void onBeginUpdateBatch(); michael@0: michael@0: /** michael@0: * Notifies that a batch transaction has ended. michael@0: */ michael@0: void onEndUpdateBatch(); michael@0: michael@0: /** michael@0: * Notifies that an item (any type) was added. Called after the actual michael@0: * addition took place. michael@0: * When a new item is created, all the items following it in the same folder michael@0: * will have their index shifted down, but no additional notifications will michael@0: * be sent. michael@0: * michael@0: * @param aItemId michael@0: * The id of the item that was added. michael@0: * @param aParentId michael@0: * The id of the folder to which the item was added. michael@0: * @param aIndex michael@0: * The item's index in the folder. michael@0: * @param aItemType michael@0: * The type of the added item (see TYPE_* constants below). michael@0: * @param aURI michael@0: * The URI of the added item if it was TYPE_BOOKMARK, null otherwise. michael@0: * @param aTitle michael@0: * The title of the added item. michael@0: * @param aDateAdded michael@0: * The stored date added value, in microseconds from the epoch. michael@0: * @param aGUID michael@0: * The unique ID associated with the item. michael@0: * @param aParentGUID michael@0: * The unique ID associated with the item's parent. michael@0: */ michael@0: void onItemAdded(in long long aItemId, michael@0: in long long aParentId, michael@0: in long aIndex, michael@0: in unsigned short aItemType, michael@0: in nsIURI aURI, michael@0: in AUTF8String aTitle, michael@0: in PRTime aDateAdded, michael@0: in ACString aGUID, michael@0: in ACString aParentGUID); michael@0: michael@0: /** michael@0: * Notifies that an item was removed. Called after the actual remove took michael@0: * place. michael@0: * When an item is removed, all the items following it in the same folder michael@0: * will have their index shifted down, but no additional notifications will michael@0: * be sent. michael@0: * michael@0: * @param aItemId michael@0: * The id of the item that was removed. michael@0: * @param aParentId michael@0: * The id of the folder from which the item was removed. michael@0: * @param aIndex michael@0: * The bookmark's index in the folder. michael@0: * @param aItemType michael@0: * The type of the item to be removed (see TYPE_* constants below). michael@0: * @param aURI michael@0: * The URI of the added item if it was TYPE_BOOKMARK, null otherwise. michael@0: * @param aGUID michael@0: * The unique ID associated with the item. michael@0: * @param aParentGUID michael@0: * The unique ID associated with the item's parent. michael@0: */ michael@0: void onItemRemoved(in long long aItemId, michael@0: in long long aParentId, michael@0: in long aIndex, michael@0: in unsigned short aItemType, michael@0: in nsIURI aURI, michael@0: in ACString aGUID, michael@0: in ACString aParentGUID); michael@0: michael@0: /** michael@0: * Notifies that an item's information has changed. This will be called michael@0: * whenever any attributes like "title" are changed. michael@0: * michael@0: * @param aItemId michael@0: * The id of the item that was changed. michael@0: * @param aProperty michael@0: * The property which changed. Can be null for the removal of all of michael@0: * the annotations, in this case aIsAnnotationProperty is true. michael@0: * @param aIsAnnotationProperty michael@0: * Whether or not aProperty is the name of an annotation. If true michael@0: * aNewValue is always an empty string. michael@0: * @param aNewValue michael@0: * For certain properties, this is set to the new value of the michael@0: * property (see the list below). michael@0: * @param aLastModified michael@0: * If lastModified changed, this parameter is the new value, otherwise michael@0: * it's set to 0. michael@0: * @param aItemType michael@0: * The type of the item to be removed (see TYPE_* constants below). michael@0: * @param aParentId michael@0: * The id of the folder containing the item. michael@0: * @param aGUID michael@0: * The unique ID associated with the item. michael@0: * @param aParentGUID michael@0: * The unique ID associated with the item's parent. michael@0: * michael@0: * @note List of values that may be associated with properties: michael@0: * aProperty | aNewValue michael@0: * ===================================================================== michael@0: * cleartime | Empty string (all visits to this item were removed). michael@0: * title | The new title. michael@0: * favicon | The "moz-anno" URL of the new favicon. michael@0: * uri | new URL. michael@0: * tags | Empty string (tags for this item changed) michael@0: * dateAdded | PRTime (as string) when the item was first added. michael@0: * lastModified | PRTime (as string) when the item was last modified. michael@0: */ michael@0: void onItemChanged(in long long aItemId, michael@0: in ACString aProperty, michael@0: in boolean aIsAnnotationProperty, michael@0: in AUTF8String aNewValue, michael@0: in PRTime aLastModified, michael@0: in unsigned short aItemType, michael@0: in long long aParentId, michael@0: in ACString aGUID, michael@0: in ACString aParentGUID); michael@0: michael@0: /** michael@0: * Notifies that the item was visited. Can be invoked only for TYPE_BOOKMARK michael@0: * items. michael@0: * michael@0: * @param aItemId michael@0: * The id of the bookmark that was visited. michael@0: * @param aVisitId michael@0: * The id of the visit. michael@0: * @param aTime michael@0: * The time of the visit. michael@0: * @param aTransitionType michael@0: * The transition for the visit. See nsINavHistoryService::TRANSITION_* michael@0: * constants for a list of possible values. michael@0: * @param aURI michael@0: * The nsIURI for this bookmark. michael@0: * @param aParentId michael@0: * The id of the folder containing the item. michael@0: * @param aGUID michael@0: * The unique ID associated with the item. michael@0: * @param aParentGUID michael@0: * The unique ID associated with the item's parent. michael@0: * michael@0: * @see onItemChanged with property = "cleartime" for when all visits to an michael@0: * item are removed. michael@0: * michael@0: * @note The reported time is the time of the visit that was added, which may michael@0: * be well in the past since the visit time can be specified. This michael@0: * means that the visit the observer is told about may not be the most michael@0: * recent visit for that page. michael@0: */ michael@0: void onItemVisited(in long long aItemId, michael@0: in long long aVisitId, michael@0: in PRTime aTime, michael@0: in unsigned long aTransitionType, michael@0: in nsIURI aURI, michael@0: in long long aParentId, michael@0: in ACString aGUID, michael@0: in ACString aParentGUID); michael@0: michael@0: /** michael@0: * Notifies that an item has been moved. michael@0: * michael@0: * @param aItemId michael@0: * The id of the item that was moved. michael@0: * @param aOldParentId michael@0: * The id of the old parent. michael@0: * @param aOldIndex michael@0: * The old index inside the old parent. michael@0: * @param aNewParentId michael@0: * The id of the new parent. michael@0: * @param aNewIndex michael@0: * The index inside the new parent. michael@0: * @param aItemType michael@0: * The type of the item to be removed (see TYPE_* constants below). michael@0: * @param aGUID michael@0: * The unique ID associated with the item. michael@0: * @param aOldParentGUID michael@0: * The unique ID associated with the old item's parent. michael@0: * @param aNewParentGUID michael@0: * The unique ID associated with the new item's parent. michael@0: */ michael@0: void onItemMoved(in long long aItemId, michael@0: in long long aOldParentId, michael@0: in long aOldIndex, michael@0: in long long aNewParentId, michael@0: in long aNewIndex, michael@0: in unsigned short aItemType, michael@0: in ACString aGUID, michael@0: in ACString aOldParentGUID, michael@0: in ACString aNewParentGUID); michael@0: }; michael@0: michael@0: /** michael@0: * The BookmarksService interface provides methods for managing bookmarked michael@0: * history items. Bookmarks consist of a set of user-customizable michael@0: * folders. A URI in history can be contained in one or more such folders. michael@0: */ michael@0: michael@0: [scriptable, uuid(A78EA368-E28E-462E-897A-26606D4DDCE6)] michael@0: interface nsINavBookmarksService : nsISupports michael@0: { michael@0: /** michael@0: * The item ID of the Places root. michael@0: */ michael@0: readonly attribute long long placesRoot; michael@0: michael@0: /** michael@0: * The item ID of the bookmarks menu folder. michael@0: */ michael@0: readonly attribute long long bookmarksMenuFolder; michael@0: michael@0: /** michael@0: * The item ID of the top-level folder that contain the tag "folders". michael@0: */ michael@0: readonly attribute long long tagsFolder; michael@0: michael@0: /** michael@0: * The item ID of the unfiled-bookmarks folder. michael@0: */ michael@0: readonly attribute long long unfiledBookmarksFolder; michael@0: michael@0: /** michael@0: * The item ID of the personal toolbar folder. michael@0: */ michael@0: readonly attribute long long toolbarFolder; michael@0: michael@0: /** michael@0: * This value should be used for APIs that allow passing in an index michael@0: * where an index is not known, or not required to be specified. michael@0: * e.g.: When appending an item to a folder. michael@0: */ michael@0: const short DEFAULT_INDEX = -1; michael@0: michael@0: const unsigned short TYPE_BOOKMARK = 1; michael@0: const unsigned short TYPE_FOLDER = 2; michael@0: const unsigned short TYPE_SEPARATOR = 3; michael@0: // Dynamic containers are deprecated and unsupported. michael@0: // This const exists just to avoid reusing the value. michael@0: const unsigned short TYPE_DYNAMIC_CONTAINER = 4; michael@0: michael@0: /** michael@0: * Inserts a child bookmark into the given folder. michael@0: * michael@0: * @param aParentId michael@0: * The id of the parent folder michael@0: * @param aURI michael@0: * The URI to insert michael@0: * @param aIndex michael@0: * The index to insert at, or DEFAULT_INDEX to append michael@0: * @param aTitle michael@0: * The title for the new bookmark michael@0: * @param [optional] aGUID michael@0: * The GUID to be set for the new item. If not set, a new GUID is michael@0: * generated. Unless you've a very sound reason, such as an undo michael@0: * manager implementation, do not pass this argument. michael@0: * @return The ID of the newly-created bookmark. michael@0: * michael@0: * @note aTitle will be truncated to TITLE_LENGTH_MAX and michael@0: * aURI will be truncated to URI_LENGTH_MAX. michael@0: * @throws if aGUID is malformed. michael@0: */ michael@0: long long insertBookmark(in long long aParentId, in nsIURI aURI, michael@0: in long aIndex, in AUTF8String aTitle, michael@0: [optional] in ACString aGUID); michael@0: michael@0: /** michael@0: * Removes a child item. Used to delete a bookmark or separator. michael@0: * @param aItemId michael@0: * The child item to remove michael@0: */ michael@0: void removeItem(in long long aItemId); michael@0: michael@0: /** michael@0: * Creates a new child folder and inserts it under the given parent. michael@0: * @param aParentFolder michael@0: * The id of the parent folder michael@0: * @param aName michael@0: * The name of the new folder michael@0: * @param aIndex michael@0: * The index to insert at, or DEFAULT_INDEX to append michael@0: * @param [optional] aGUID michael@0: * The GUID to be set for the new item. If not set, a new GUID is michael@0: * generated. Unless you've a very sound reason, such as an undo michael@0: * manager implementation, do not pass this argument. michael@0: * @return The ID of the newly-inserted folder. michael@0: * @throws if aGUID is malformed. michael@0: */ michael@0: long long createFolder(in long long aParentFolder, in AUTF8String name, michael@0: in long index, michael@0: [optional] in ACString aGUID); michael@0: michael@0: /** michael@0: * Gets an undo-able transaction for removing a folder from the bookmarks michael@0: * tree. michael@0: * @param aItemId michael@0: * The id of the folder to remove. michael@0: * @return An object implementing nsITransaction that can be used to undo michael@0: * or redo the action. michael@0: * michael@0: * This method exists because complex delete->undo operations rely on michael@0: * recreated folders to have the same ID they had before they were deleted, michael@0: * so that any other items deleted in different transactions can be michael@0: * re-inserted correctly. This provides a safe encapsulation of this michael@0: * functionality without exposing the ability to recreate folders with michael@0: * specific IDs (potentially dangerous if abused by other code!) in the michael@0: * public API. michael@0: */ michael@0: nsITransaction getRemoveFolderTransaction(in long long aItemId); michael@0: michael@0: /** michael@0: * Convenience function for container services. Removes michael@0: * all children of the given folder. michael@0: * @param aItemId michael@0: * The id of the folder to remove children from. michael@0: */ michael@0: void removeFolderChildren(in long long aItemId); michael@0: michael@0: /** michael@0: * Moves an item to a different container, preserving its contents. michael@0: * @param aItemId michael@0: * The id of the item to move michael@0: * @param aNewParentId michael@0: * The id of the new parent michael@0: * @param aIndex michael@0: * The index under aNewParent, or DEFAULT_INDEX to append michael@0: * michael@0: * NOTE: When moving down in the same container we take into account the michael@0: * removal of the original item. If you want to move from index X to michael@0: * index Y > X you must use moveItem(id, folder, Y + 1) michael@0: */ michael@0: void moveItem(in long long aItemId, in long long aNewParentId, in long aIndex); michael@0: michael@0: /** michael@0: * Inserts a bookmark separator into the given folder at the given index. michael@0: * The separator can be removed using removeChildAt(). michael@0: * @param aParentId michael@0: * The id of the parent folder michael@0: * @param aIndex michael@0: * The separator's index under folder, or DEFAULT_INDEX to append michael@0: * @param [optional] aGUID michael@0: * The GUID to be set for the new item. If not set, a new GUID is michael@0: * generated. Unless you've a very sound reason, such as an undo michael@0: * manager implementation, do not pass this argument. michael@0: * @return The ID of the new separator. michael@0: * @throws if aGUID is malformed. michael@0: */ michael@0: long long insertSeparator(in long long aParentId, in long aIndex, michael@0: [optional] in ACString aGUID); michael@0: michael@0: /** michael@0: * Get the itemId given the containing folder and the index. michael@0: * @param aParentId michael@0: * The id of the diret parent folder of the item michael@0: * @param aIndex michael@0: * The index of the item within the parent folder. michael@0: * Pass DEFAULT_INDEX for the last item. michael@0: * @return The ID of the found item, -1 if the item does not exists. michael@0: */ michael@0: long long getIdForItemAt(in long long aParentId, in long aIndex); michael@0: michael@0: /** michael@0: * Set the title for an item. michael@0: * @param aItemId michael@0: * The id of the item whose title should be updated. michael@0: * @param aTitle michael@0: * The new title for the bookmark. michael@0: * michael@0: * @note aTitle will be truncated to TITLE_LENGTH_MAX. michael@0: */ michael@0: void setItemTitle(in long long aItemId, in AUTF8String aTitle); michael@0: michael@0: /** michael@0: * Get the title for an item. michael@0: * michael@0: * If no item title is available it will return a void string (null in JS). michael@0: * michael@0: * @param aItemId michael@0: * The id of the item whose title should be retrieved michael@0: * @return The title of the item. michael@0: */ michael@0: AUTF8String getItemTitle(in long long aItemId); michael@0: michael@0: /** michael@0: * Set the date added time for an item. michael@0: */ michael@0: void setItemDateAdded(in long long aItemId, in PRTime aDateAdded); michael@0: /** michael@0: * Get the date added time for an item. michael@0: */ michael@0: PRTime getItemDateAdded(in long long aItemId); michael@0: michael@0: /** michael@0: * Set the last modified time for an item. michael@0: * michael@0: * @note This is the only method that will send an itemChanged notification michael@0: * for the property. lastModified will still be updated in michael@0: * any other method that changes an item property, but we will send michael@0: * the corresponding itemChanged notification instead. michael@0: */ michael@0: void setItemLastModified(in long long aItemId, in PRTime aLastModified); michael@0: /** michael@0: * Get the last modified time for an item. michael@0: * michael@0: * @note When an item is added lastModified is set to the same value as michael@0: * dateAdded. michael@0: */ michael@0: PRTime getItemLastModified(in long long aItemId); michael@0: michael@0: /** michael@0: * Get the URI for a bookmark item. michael@0: */ michael@0: nsIURI getBookmarkURI(in long long aItemId); michael@0: michael@0: /** michael@0: * Get the index for an item. michael@0: */ michael@0: long getItemIndex(in long long aItemId); michael@0: michael@0: /** michael@0: * Changes the index for a item. This method does not change the indices of michael@0: * any other items in the same folder, so ensure that the new index does not michael@0: * already exist, or change the index of other items accordingly, otherwise michael@0: * the indices will become corrupted. michael@0: * michael@0: * WARNING: This is API is intended for scenarios such as folder sorting, michael@0: * where the caller manages the indices of *all* items in the folder. michael@0: * You must always ensure each index is unique after a reordering. michael@0: * michael@0: * @param aItemId The id of the item to modify michael@0: * @param aNewIndex The new index michael@0: * michael@0: * @throws If aNewIndex is out of bounds. michael@0: */ michael@0: void setItemIndex(in long long aItemId, in long aNewIndex); michael@0: michael@0: /** michael@0: * Get an item's type (bookmark, separator, folder). michael@0: * The type is one of the TYPE_* constants defined above. michael@0: */ michael@0: unsigned short getItemType(in long long aItemId); michael@0: michael@0: /** michael@0: * Checks whether a folder is marked as read-only. michael@0: * If this is set to true, UI will not allow the user to add, remove, michael@0: * or reorder children in this folder. The default for all folders is false. michael@0: * Note: This does not restrict API calls, only UI actions. michael@0: * michael@0: * @param aItemId michael@0: * the item-id of the folder. michael@0: */ michael@0: boolean getFolderReadonly(in long long aItemId); michael@0: michael@0: /** michael@0: * Sets or unsets the readonly flag from a folder. michael@0: * If this is set to true, UI will not allow the user to add, remove, michael@0: * or reorder children in this folder. The default for all folders is false. michael@0: * Note: This does not restrict API calls, only UI actions. michael@0: * michael@0: * @param aFolder michael@0: * the item-id of the folder. michael@0: * @param aReadOnly michael@0: * the read-only state (boolean). michael@0: */ michael@0: void setFolderReadonly(in long long aFolder, in boolean aReadOnly); michael@0: michael@0: /** michael@0: * Returns true if the given URI is in any bookmark folder. If you want the michael@0: * results to be redirect-aware, use getBookmarkedURIFor() michael@0: */ michael@0: boolean isBookmarked(in nsIURI aURI); michael@0: michael@0: /** michael@0: * Used to see if the given URI is bookmarked, or any page that redirected to michael@0: * it is bookmarked. For example, if I bookmark "mozilla.org" by manually michael@0: * typing it in, and follow the bookmark, I will get redirected to michael@0: * "www.mozilla.org". Logically, this new page is also bookmarked. This michael@0: * function, if given "www.mozilla.org", will return the URI of the bookmark, michael@0: * in this case "mozilla.org". michael@0: * michael@0: * If there is no bookmarked page found, it will return NULL. michael@0: * michael@0: * @note The function will only return bookmarks in the first 2 levels of michael@0: * redirection (1 -> 2 -> aURI). michael@0: */ michael@0: nsIURI getBookmarkedURIFor(in nsIURI aURI); michael@0: michael@0: /** michael@0: * Change the bookmarked URI for a bookmark. michael@0: * This changes which "place" the bookmark points at, michael@0: * which means all annotations, etc are carried along. michael@0: */ michael@0: void changeBookmarkURI(in long long aItemId, in nsIURI aNewURI); michael@0: michael@0: /** michael@0: * Get the parent folder's id for an item. michael@0: */ michael@0: long long getFolderIdForItem(in long long aItemId); michael@0: michael@0: /** michael@0: * Returns the list of bookmark ids that contain the given URI. michael@0: */ michael@0: void getBookmarkIdsForURI(in nsIURI aURI, [optional] out unsigned long count, michael@0: [array, retval, size_is(count)] out long long bookmarks); michael@0: michael@0: /** michael@0: * Associates the given keyword with the given bookmark. michael@0: * michael@0: * Use an empty keyword to clear the keyword associated with the URI. michael@0: * In both of these cases, succeeds but does nothing if the URL/keyword is not found. michael@0: */ michael@0: void setKeywordForBookmark(in long long aItemId, in AString aKeyword); michael@0: michael@0: /** michael@0: * Retrieves the keyword for the given URI. Will be void string michael@0: * (null in JS) if no such keyword is found. michael@0: */ michael@0: AString getKeywordForURI(in nsIURI aURI); michael@0: michael@0: /** michael@0: * Retrieves the keyword for the given bookmark. Will be void string michael@0: * (null in JS) if no such keyword is found. michael@0: */ michael@0: AString getKeywordForBookmark(in long long aItemId); michael@0: michael@0: /** michael@0: * Returns the URI associated with the given keyword. Empty if no such michael@0: * keyword is found. michael@0: */ michael@0: nsIURI getURIForKeyword(in AString keyword); michael@0: michael@0: /** michael@0: * Adds a bookmark observer. If ownsWeak is false, the bookmark service will michael@0: * keep an owning reference to the observer. If ownsWeak is true, then michael@0: * aObserver must implement nsISupportsWeakReference, and the bookmark michael@0: * service will keep a weak reference to the observer. michael@0: */ michael@0: void addObserver(in nsINavBookmarkObserver observer, in boolean ownsWeak); michael@0: michael@0: /** michael@0: * Removes a bookmark observer. michael@0: */ michael@0: void removeObserver(in nsINavBookmarkObserver observer); michael@0: michael@0: /** michael@0: * Runs the passed callback inside of a database transaction. michael@0: * Use this when a lot of things are about to change, for example michael@0: * adding or deleting a large number of bookmark items. Calls can michael@0: * be nested. Observers are notified when batches begin and end, via michael@0: * nsINavBookmarkObserver.onBeginUpdateBatch/onEndUpdateBatch. michael@0: * michael@0: * @param aCallback michael@0: * nsINavHistoryBatchCallback interface to call. michael@0: * @param aUserData michael@0: * Opaque parameter passed to nsINavBookmarksBatchCallback michael@0: */ michael@0: void runInBatchMode(in nsINavHistoryBatchCallback aCallback, michael@0: in nsISupports aUserData); michael@0: };