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.
Inserts a child bookmark into the given folder.
@note aTitle will be truncated to TITLE_LENGTH_MAX and
aURI will be truncated to URI_LENGTH_MAX.
@throws if aGuid is malformed.
| aParentId | The id of the parent folder |
| aURI | The URI to insert |
| aIndex | The index to insert at, or DEFAULT_INDEX to append |
| aTitle | The title for the new bookmark |
| [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. |
| The ID of the newly-created bookmark. |
Removes a child item. Used to delete a bookmark or separator.
| aItemId | The child item to remove |
Creates a new child folder and inserts it under the given parent.
| aParentFolder | The id of the parent folder |
| aName | The name of the new folder |
| aIndex | The index to insert at, or DEFAULT_INDEX to append |
| [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. |
| The ID of the newly-inserted folder. @throws if aGuid is malformed. |
Gets an undo-able transaction for removing a folder from the bookmarks
tree.
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.
| aItemId | The id of the folder to remove. |
| An object implementing nsITransaction that can be used to undo or redo the action. |
Convenience function for container services. Removes
all children of the given folder.
| aItemId | The id of the folder to remove children from. |
Moves an item to a different container, preserving its contents.
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)
| aItemId | The id of the item to move |
| aNewParentId | The id of the new parent |
| aIndex | The index under aNewParent, or DEFAULT_INDEX to append |
Inserts a bookmark separator into the given folder at the given index.
The separator can be removed using removeChildAt().
| aParentId | The id of the parent folder |
| aIndex | The separator's index under folder, or DEFAULT_INDEX to append |
| [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. |
| The ID of the new separator. @throws if aGuid is malformed. |
Get the itemId given the containing folder and the index.
| aParentId | The id of the diret parent folder of the item |
| aIndex | The index of the item within the parent folder. Pass DEFAULT_INDEX for the last item. |
| The ID of the found item, -1 if the item does not exists. |
Set the title for an item.
@note aTitle will be truncated to TITLE_LENGTH_MAX.
| aItemId | The id of the item whose title should be updated. |
| aTitle | The new title for the bookmark. |
Get the title for an item.
If no item title is available it will return a void string (null in JS).
| aItemId | The id of the item whose title should be retrieved |
| The title of the item. |
Set the date added time for an item.
Get the date added time for an item.
Set the last modified time for an item.
@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.
Get the last modified time for an item.
@note When an item is added lastModified is set to the same value as
dateAdded.
Get the URI for a bookmark item.
Get the index for an item.
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.
@throws If aNewIndex is out of bounds.
| aItemId | The id of the item to modify |
| aNewIndex | The new index |
Get an item’s type (bookmark, separator, folder).
The type is one of the TYPE_* constants defined above.
Returns true if the given URI is in any bookmark folder. If you want the
results to be redirect-aware, use getBookmarkedURIFor()
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).
Change the bookmarked URI for a bookmark.
This changes which “place” the bookmark points at,
which means all annotations, etc are carried along.
Get the parent folder’s id for an item.
Returns the list of bookmark ids that contain the given URI.
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.
Retrieves the keyword for the given URI. Will be void string
(null in JS) if no such keyword is found.
Retrieves the keyword for the given bookmark. Will be void string
(null in JS) if no such keyword is found.
Returns the URI associated with the given keyword. Empty if no such
keyword is found.
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.
Removes a bookmark observer.
Gets an array of registered nsINavBookmarkObserver objects.
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.
| aCallback | nsINavHistoryBatchCallback interface to call. |
| aUserData | Opaque parameter passed to nsINavBookmarksBatchCallback |
The item ID of the Places root.
The item ID of the bookmarks menu folder.
The item ID of the top-level folder that contain the tag “folders”.
The item ID of the unfiled-bookmarks folder.
The item ID of the personal toolbar folder.
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.