nsINavBookmarksService

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.
1.0
28
Introduced
Gecko 1.8
Inherits from: nsISupports Last changed in Gecko 14.0 (Firefox 14.0 / Thunderbird 14.0 / SeaMonkey 2.11)

Implemented by: @mozilla.org/browser/nav-bookmarks-service;1. To use this service, use:

var navBookmarksService = Components.classes["@mozilla.org/browser/nav-bookmarks-service;1"]
                          .getService(Components.interfaces.nsINavBookmarksService);

Method overview

void addObserver(in nsINavBookmarkObserver observer, in boolean ownsWeak);
void beginUpdateBatch(); Obsolete since Gecko 1.9
void changeBookmarkURI(in long long aItemId, in nsIURI aNewURI);
long long createDynamicContainer(in long long aParentFolder, in AUTF8String aName, in AString aContractId, in long aIndex); Renamed from createContainer in Gecko 1.9 Obsolete since Gecko 13.0
long long createFolder(in long long aParentFolder, in AUTF8String name, in long index);
void endUpdateBatch(); Obsolete since Gecko 1.9
void exportBookmarksHTML(in nsIFile file); Obsolete since Gecko 1.9
nsIURI getBookmarkedURIFor(in nsIURI aURI);
void getBookmarkFoldersTArray(in nsIURI aURI, in PRInt64Array aResult); Native code only! Obsolete since Gecko 1.9
void getBookmarkIdsForURI(in nsIURI aURI, [optional] out unsigned long count, [array, retval, size_is(count)] out long long bookmarks); Renamed from getBookmarkFolders in Gecko 1.9
void getBookmarkIdsForURITArray(in nsIURI aURI, in PRInt64Array aResult); Native code only! Obsolete since Gecko 2.0
nsIURI getBookmarkURI(in long long aItemId);
long long getChildFolder(in long long aFolder, in AString aSubFolder); Obsolete since Gecko 2.0
long long getFolderIdForItem(in long long aItemId);
boolean getFolderReadonly(in long long aItemId);
AString getFolderTitle(in PRInt64 folder); Obsolete since Gecko 1.9
nsIURI getFolderURI(in PRInt64 folder); Obsolete since Gecko 1.9
long long getIdForItemAt(in long long aParentId, in long aIndex);
PRTime getItemDateAdded(in long long aItemId);
AString getItemGUID(in long long aItemId); Obsolete since Gecko 14.0
long long getItemIdForGUID(in AString aGUID); Obsolete since Gecko 14.0
long getItemIndex(in long long aItemId);
PRTime getItemLastModified(in long long aItemId);
AUTF8String getItemTitle(in long long aItemId);
unsigned short getItemType(in long long aItemId);
AString getKeywordForBookmark(in long long aItemId);
AString getKeywordForURI(in nsIURI aURI);
nsITransaction getRemoveFolderTransaction(in long long aItemId);
nsIURI getURIForKeyword(in AString keyword);
void importBookmarksHTML(in nsIURI url); Obsolete since Gecko 1.9
void importBookmarksHTMLToFolder(in nsIURI url, in PRInt64 folder); Obsolete since Gecko 1.9
PRInt32 indexOfFolder(in PRInt64 parent, in PRInt64 folder); Obsolete since Gecko 1.9
PRInt32 indexOfItem(in PRInt64 folder, in nsIURI uri); Obsolete since Gecko 1.9
long long insertBookmark(in long long aParentId, in nsIURI aURI, in long aIndex, in AUTF8String aTitle);
void insertItem(in PRInt64 folder, in nsIURI item, in PRInt32 index); Obsolete since Gecko 1.9
long long insertSeparator(in long long aParentId, in long aIndex);
boolean isBookmarked(in nsIURI aURI);
void moveFolder(in PRInt64 folder, in PRInt64 newParent, in PRInt32 index); Obsolete since Gecko 1.9
void moveItem(in long long aItemId, in long long aNewParentId, in long aIndex);
void removeChildAt(in long long aFolder, in long aIndex); Obsolete since Gecko 2.0
void removeFolder(in long long aFolder); Obsolete since Gecko 2.0
void removeFolderChildren(in long long aItemId);
void removeItem(in long long aItemId);
void removeObserver(in nsINavBookmarkObserver observer);
void replaceItem(in PRInt64 folder, in nsIURI item, in nsIURI newItem); Obsolete since Gecko 1.9
void runInBatchMode(in nsINavHistoryBatchCallback aCallback, in nsISupports aUserData);
void setFolderReadonly(in long long aFolder, in boolean aReadOnly);
void setFolderTitle(in PRInt64 folder, in AString title); Obsolete since Gecko 1.9
void setItemDateAdded(in long long aItemId, in PRTime aDateAdded);
void setItemGUID(in long long aItemId, in AString aGUID); Obsolete since Gecko 14.0
void setItemIndex(in long long aItemId, in long aNewIndex);
void setItemLastModified(in long long aItemId, in PRTime aLastModified);
void setItemTitle(in long long aItemId, in AUTF8String aTitle);
void setKeywordForBookmark(in long long aItemId, in AString aKeyword);
void setKeywordForURI(in nsIURI uri, in AString keyword); Obsolete since Gecko 1.9

Attributes

Attribute Type Description
bookmarksMenuFolder long long The item ID of the Bookmarks Menu folder. Read only. Renamed from bookmarksRoot in Gecko 1.9
placesRoot long long The item ID of the top-level folder that contains bookmarks, tags and all other Places data. This contains administrative data as well as user data, and is therefore not recommended for use in queries. Read only.
tagsFolder long long The item ID of the top-level folder that contains the tag "folders". Read only. Renamed from tagRoot in Gecko 1.9
toolbarFolder long long The item ID of the personal toolbar folder. Read only. Renamed from toolbarRoot in Gecko 1.9
unfiledBookmarksFolder long long The item ID of the Unfiled Bookmarks folder. Read only.

Constants

Constant Value Description
DEFAULT_INDEX -1 This is the default index; this value should be used for APIs that allow passing in an index where the index is not known or is not required to be specified, such as when appending an item to a folder.
TYPE_BOOKMARK 1 This is an index for type "Bookmark".
TYPE_FOLDER 2 This is an index for type "Folder".
TYPE_SEPARATOR 3 This is an index for type "Separator".
TYPE_DYNAMIC_CONTAINER 4 This is an index for type "Dynamic Container".

Methods

addObserver()

This method 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
);
Parameters
observer
The bookmark observer to be added.
ownsWeak
The owning reference state (boolean).

Obsolete since Gecko 1.9 (Firefox 3)

beginUpdateBatch()

Causes observers to be notified of a beginUpdateBatch when a lot of things are about to change. Calls can be nested, observers will only be notified when all batches begin/end.

It is EXTREMELY IMPORTANT that you call EndUpdateBatch() for each call to beginUpdateBatch. If you do not do this, certain parts of the UI will not get updated and any changes to bookmarks will not get written to disk. From C++ code inside the places component, use nsBookmarksUpdateBatcher defined in nsNavBookmarks.h to scope batches. For JS or from other components, just please be very careful to close the batch, especially when encountering an error and returning early.

void beginUpdateBatch();
Parameters

None.

changeBookmarkURI()

This method changes the bookmarked URI for a bookmark. It changes which "place" the bookmark points at, which means all annotations, and so on are carried along.

void changeBookmarkURI(
  in nsIURI oldURI, Obsolete since Gecko 1.9
  in long long aItemId, 
  in nsIURI aNewURI
);
Parameters
oldURI Obsolete since Gecko 1.9
The URI of the item to be changed.
aItemId
The item whose bookmark URI needs to be changed.
aNewURI
The new URI.

Renamed from createContainer in Gecko 1.9

createDynamicContainer()

Obsolete since Gecko 13.0 (Firefox 13.0 / Thunderbird 13.0 / SeaMonkey 2.10)
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

This method creates a dynamic container under the given parent folder.

long long createDynamicContainer(
  in long long aParentFolder,
  in AUTF8String aName,
  in AString aContractId,
  in long aIndex
);
Parameters
aParentFolder
The ID of the parent folder.
aName
The name of the new folder.
aContractId
The contract ID of the service which is to manipulate this container.
aIndex
The index to insert at, or DEFAULT_INDEX to append to the end of the list.
Return value

Returns the ID of the newly-inserted folder.

createFolder()

This method creates a new child folder and inserts it under the given parent.

long long createFolder(
  in long long aParentFolder,
  in AUTF8String name,
  in long index
);
Parameters
aParentFolder
The ID of the parent folder.
name
The name of the new folder.
index
The index to insert at, or DEFAULT_INDEX to append to the end of the list.
Return value

Returns the ID of the newly-inserted folder.

Obsolete since Gecko 1.9 (Firefox 3)

endUpdateBatch()

Causes observers to be notified of an endUpdateBatch when a batch is done changing. Should match beginUpdateBatch() or bad things will happen.

void endUpdateBatch();
Parameters

None.

Obsolete since Gecko 1.9 (Firefox 3)

exportBookmarksHTML()

Saves the current bookmarks hierarchy to a bookmarks.html file.

void exportBookmarksHTML(
  in nsIFile file
);
Parameters
file
The nsIFile to export the bookmarks to.

getBookmarkedURIFor()

This method is 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".

Note: Will only return bookmarks in the first 3 levels of redirection (1 -> 2 -> 3 -> aURI).

nsIURI getBookmarkedURIFor(
  in nsIURI aURI
);
Parameters
aURI
The URI that needs to be checked if it is bookmarked or not.
Return value

Native code only!

getBookmarkFoldersTArray

Obsolete since Gecko 1.9 (Firefox 3)
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

TArray version of getBookmarkFolders() for ease of use in C++ code. Pass in a reference to a TArray; it will get cleared and filled with the resulting list of folder IDs.

void getBookmarkFoldersTArray(
  in nsIURI aURI,
  in PRInt64Array aResult
);
Parameters
aURI
 
aResult
 

Returns an nsIURI representing the URI whose bookmark is to be retrieved. If there is no bookmarked page found, it will return null.

Renamed from getBookmarkFolders in Gecko 1.9

getBookmarkIdsForURI()

This method retrieves the list of bookmark IDs that contain the given URI.

void getBookmarkIdsForURI(
  in nsIURI aURI,
  out unsigned long count, Optional
  [array, retval, size_is(count)] out long long bookmarks
);
Parameters
aURI
The URI whose list of bookmark IDs is to be retrieved.
count
The count of bookmark IDs.
bookmarks
The list of bookmark IDs.

Native code only!

getBookmarkIdsForURITArray

Obsolete since Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

This method is a TArray version of getBookmarkIdsForURI() for ease of use in C++ code. Pass in a reference to a TArray; it will get cleared and filled with the resulting list of folder IDs.

void getBookmarkIdsForURITArray(
  in nsIURI aURI,
  in PRInt64Array aResult
);
Parameters
aURI
The URI whose list of bookmark IDs is to be retrieved.
aResult
The list of bookmark IDs.

Requires Gecko 1.9 (Firefox 3)

getBookmarkURI()

This method retrieves the URI for a bookmark item.

nsIURI getBookmarkURI(
  in long long aItemId
);
Parameters
aItemId
The ID of the bookmark item whose URI is to be retrieved.
Return value

Returns a nsIURI representing the URI of the bookmark.

Obsolete since Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

getChildFolder()

This method retrieves the ID of a child folder with the given name. This does not recurse, so you have to give it an immediate sibling of the given folder.

long long getChildFolder(
  in long long aFolder,
  in AString aSubFolder
);
Parameters
aFolder
Parent folder whose children we will search.
aSubFolder
Name of the folder to search for in folder.
Return value

Returns the ID of a child folder with the given name. If the given subfolder doesn't exist, 0 is returned.

Requires Gecko 1.9 (Firefox 3)

getFolderIdForItem()

This method retrieves the parent folder's ID for an item.

long long getFolderIdForItem(
  in long long aItemId
);
Parameters
aItemId
The item whose parent folder's ID is to retrieved.
Return value

Returns the parent folder's ID for the given item.

getFolderReadonly()

This method checks whether a folder is marked as read-only. If this is set to true, UI will not allow the user to add, remove, or reorder children in this folder. The default for all folders is false.

Note: This does not restrict API calls, only UI actions.

boolean getFolderReadonly(
  in long long aItemId
);
Parameters
aItemId
The item ID of the folder.
Return value

Returns true if the folder is marked as read-only, otherwise returns false.

Obsolete since Gecko 1.9 (Firefox 3)

getFolderTitle()

Note: getItemTitle() provides an alternative for this method.

Get the title for a bookmark folder.

AString getFolderTitle(
  in PRInt64 folder
);
Parameters
folder
The folder whose title should be retrieved.
Return value

The title of the folder.

Exceptions thrown
invalid argument exception
If it can not find a folder with the given ID.

Obsolete since Gecko 1.9 (Firefox 3)

getFolderURI()

Note: getBookmarkURI() provides an alternative for this method.

Get the url for a bookmark folder.

nsIURI getFolderURI(
  in PRInt64 folder
);
Parameters
folder
The folder whose URI should be retrieved.
Return value

The URI of the folder.

Requires Gecko 1.9 (Firefox 3)

getIdForItemAt()

Returns the item ID for the item at the specified index within a particular folder.

long long getIdForItemAt(
  in long long aParentId,
  in long aIndex
);
Parameters
aParentId
The ID of the direct parent folder of the item whose ID is to be obtained.
aIndex
The index of the item within the folder specified by aParentID for the item whose ID is to be returned. Specify DEFAULT_INDEX to return the last item in the folder.
Return value

The item ID for the specified item or -1 if the item does not exist.

Requires Gecko 1.9 (Firefox 3)

getItemDateAdded()

This method retrieves the date added time for an item.

PRTime getItemDateAdded(
  in long long aItemId
);
Parameters
aItemId
The ID of the item whose added date time is to be retrieved.
Return value

Returns the date added time for the given item.

Requires Gecko 1.9 (Firefox 3)

getItemGUID()

Obsolete since Gecko 14.0 (Firefox 14.0 / Thunderbird 14.0 / SeaMonkey 2.11)
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

This method retrieves a globally unique identifier for an item, meant to be used in sync scenarios. Even if their contents are exactly the same (including an item in a different profile with the same ItemId), the GUID would be different.

AString getItemGUID(
  in long long aItemId
);
Parameters
aItemId
The ID of the item to get the GUID for.
Return value

Returns the GUID string.

Requires Gecko 1.9 (Firefox 3)

getItemIdForGUID()

Obsolete since Gecko 14.0 (Firefox 14.0 / Thunderbird 14.0 / SeaMonkey 2.11)
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

This method retrieves the ID of the item with the given GUID.

long long getItemIdForGUID(
  in AString aGUID
);
Parameters
aGUID
The GUID string of the item to search for.
Return value

Returns the item ID, or -1 if not found.

Requires Gecko 1.9 (Firefox 3)

getItemIndex()

This method retrieves the index for an item.

long getItemIndex(
  in long long aItemId
);
Parameters
aItemId
The ID of the item whose index is to be retrieved.
Return value

Returns the index of the given item.

Requires Gecko 1.9 (Firefox 3)

getItemLastModified()

This method retrieves the last modified time for an item.

Note: When an item is added lastModified is set to the same value as dateAdded.

PRTime getItemLastModified(
  in long long aItemId
);
Parameters
aItemId
The ID of the item whose last modified time is to be retrieved.
Return value

Returns the last modified time for the given item.

getItemTitle()

This method retrieves the title for an item. If no item title is available it will return a void string (null in JS environment).

AUTF8String getItemTitle(
  in nsIURI uri, Obsolete since Gecko 1.9
  in long long aItemId 
);
Parameters
uri Obsolete since Gecko 1.9
The URI of the item whose title should be retrieved.
aItemId
The ID of the item whose title should be retrieved.
Return value

Returns the title of the item.

Requires Gecko 1.9 (Firefox 3)

getItemType()

This method retrieves an item's type (bookmark, separator, folder). The type is one of the TYPE_* constants defined above.

unsigned short getItemType(
  in long long aItemId
);
Parameters
aItemId
The ID of the item whose type is to be retrieved.
Return value

Returns one of the above defined TYPE_* for the given item.

Requires Gecko 1.9 (Firefox 3)

getKeywordForBookmark()

This method retrieves the keyword for the given bookmark. Will be void string (null in JS) if no such keyword is found.

AString getKeywordForBookmark(
  in long long aItemId
);
Parameters
aItemId
The item (bookmark) whose keyword is to be retrieved.
Return value

Returns the keyword for the given bookmark.

getKeywordForURI()

This method retrieves the keyword for the given URI. Will be void string (null in JS) if no such keyword is found.

AString getKeywordForURI(
  in nsIURI aURI
);
Parameters
aURI
The URI whose keyword is to be retrieved.
Return value

Returns the keyword for the given URI.

getRemoveFolderTransaction()

This method retrieves 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.

nsITransaction getRemoveFolderTransaction(
  in long long aItemId
);
Parameters
aItemId
The ID of the folder to remove.
Return value

Returns an object implementing nsITransaction that can be used to undo or redo the action.

getURIForKeyword()

This method retrieves the URI associated with the given keyword.

nsIURI getURIForKeyword(
  in AString keyword
);
Parameters
keyword
The keyword whose URI is to be retrieved.
Return value

Returns a nsIURI representing the URI associated with the given keyword. Empty if no such keyword is found.

Obsolete since Gecko 1.9 (Firefox 3)

importBookmarksHTML()

Loads the given bookmarks.html file and merges it with the current bookmarks hierarchy.

void importBookmarksHTML(
  in nsIURI url
);
Parameters
url
The url of the bookmarks.html file to be merged.

Obsolete since Gecko 1.9 (Firefox 3)

importBookmarksHTMLToFolder()

Loads the given bookmarks.html file and puts it in the given folder.

void importBookmarksHTMLToFolder(
  in nsIURI url,
  in PRInt64 folder
);
Parameters
url
The url of the bookmarks.html file to be imported.
folder
The folder where the bookmarks should be imported.

Obsolete since Gecko 1.9 (Firefox 3)

indexOfFolder()

Note: getItemIndex() provides an alternative for this method.

Returns the index of the given subfolder in its parent.

PRInt32 indexOfFolder(
  in PRInt64 parent,
  in PRInt64 folder
);
Parameters
parent
The parent folder containing the folder.
folder
The ID of the folder.
Return value

The index of the subfolder or -1 if the subfolder is not present in the parent folder.

Obsolete since Gecko 1.9 (Firefox 3)

indexOfItem()

Note: getItemIndex() provides an alternative for this method.

Returns the index of the given item in the given folder.

PRInt32 indexOfItem(
  in PRInt64 folder,
  in nsIURI uri
);
Parameters
folder
The folder containing the item.
uri
The uri of the item.
Return value

The index of the item or -1 if the item is not present in the folder.

Requires Gecko 1.9 (Firefox 3)

insertBookmark()

This method inserts a child bookmark into the given folder.

long long insertBookmark(
  in long long aParentId,
  in nsIURI aURI,
  in long aIndex,
  in AUTF8String aTitle
);
Parameters
aParentId
The ID of the parent folder.
aURI
The URI to insert.
aIndex
The index to insert at, or DEFAULT_INDEX to append to the end of the list.
aTitle
The title for the new bookmark.
Return value

Returns the ID of the newly-created bookmark.

Obsolete since Gecko 1.9 (Firefox 3)

insertItem()

Note: insertBookmark() provides an alternative for this method.

Inserts a child item into the given folder. If this item already exists in the given folder, it will be moved to the new position.

void insertItem(
  in PRInt64 folder,
  in nsIURI item,
  in PRInt32 index
);
Parameters
folder
The id of the parent folder.
item
The URI to insert.
index
The index to insert at, or -1 to append.

insertSeparator()

This method inserts a bookmark separator into the given folder at the given index. The separator can be removed using getIdForItemAt() and removeItem().

long long insertSeparator(
  in long long aParentId,
  in long aIndex
);
Parameters
aParentId
The ID of the parent folder in which to insert the separator.
aIndex
The separator's index under the folder, or DEFAULT_INDEX to append to the end of the list.
Return value

The ID of the new separator.

isBookmarked()

This method checks whether or not the given URI is in any bookmark folder. If you want the results to be redirect-aware, use getBookmarkedURIFor()

boolean isBookmarked(
  in nsIURI aURI
);
Parameters
aURI
The URI whose existence in any bookmark folder is needed to be checked.
Return value

Returns true if the given URI is in any bookmark folder, otherwise returns false.

Obsolete since Gecko 1.9 (Firefox 3)

moveFolder()

Note: moveItem() provides an alternative for this method.

Moves a folder to a different container, preserving its contents.

void moveFolder(
  in PRInt64 folder,
  in PRInt64 newParent,
  in PRInt32 index
);
Parameters
folder
The folder to move.
newParent
The id of the folder's new parent.
index
The folder's index under newParent, or -1 to append.

Requires Gecko 1.9 (Firefox 3)

moveItem()

This method 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)

void moveItem(
  in long long aItemId,
  in long long aNewParentId,
  in long aIndex
);
Parameters
aItemId
The ID of the item to move.
aNewParentId
The ID of the new parent.
aIndex
The index under aNewParentId to insert at, or DEFAULT_INDEX to append to the end of the list.

Obsolete since Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

removeChildAt()

Use removeItem() instead.

This method removes any type of child (item, folder, or separator) at the given index.

void removeChildAt(
  in long long aFolder,
  in long aIndex
);
Parameters
aFolder
The folder to remove a child from.
aIndex
The index of the child to remove.

Obsolete since Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

removeFolder()

Use removeItem() instead.

This method removes a folder from the bookmarks tree.

void removeFolder(
  in long long aFolder
);
Parameters
aFolder
The ID of the folder to remove.

removeFolderChildren()

This method removes all children of the given folder. Its a Convenience function for container services.

void removeFolderChildren(
  in long long aItemId
);
Parameters
aItemId
The ID of the folder to remove children from.

removeItem()

This method removes a child item. It is used to delete a bookmark or a separator.

void removeItem(
  in PRInt64 folder, Obsolete since Gecko 1.9
  in nsIURI child, Obsolete since Gecko 1.9
  in long long aItemId 
);
Parameters
folder Obsolete since Gecko 1.9
The ID of the items parent folder.
folder Obsolete since Gecko 1.9
The URI of the item to remove.
aItemId
The child item to remove.

removeObserver()

This method removes a bookmark observer.

void removeObserver(
  in nsINavBookmarkObserver observer
);
Parameters
observer
The bookmark observer to be removed.

Obsolete since Gecko 1.9 (Firefox 3)

replaceItem()

Replace an item with a different item.

void replaceItem(
  in PRInt64 folder,
  in nsIURI item,
  in nsIURI newItem
);
Parameters
folder
The folder which contains the item to replace.
item
The item which should be replaced.
newItem
The new item.

Requires Gecko 1.9 (Firefox 3)

runInBatchMode()

This method runs the passed callback in batch mode (Inside 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() and nsINavBookmarkObserver.onEndUpdateBatch().

void runInBatchMode(
  in nsINavHistoryBatchCallback aCallback,
  in nsISupports aUserData
);
Parameters
aCallback
nsINavHistoryBatchCallback interface to call.
aUserData
Opaque parameter passed to nsINavBookmarksBatchCallback.

Requires Gecko 1.9 (Firefox 3)

setFolderReadonly()

This method sets or unsets the readonly flag from a folder. If this is set to true, UI will not allow the user to add, remove, or reorder children in this folder. The default for all folders is false.

Note: This does not restrict API calls, only UI actions.

void setFolderReadonly(
  in long long aFolder,
  in boolean aReadOnly
);
Parameters
aFolder
The item-id of the folder.
aReadOnly
The read-only state.

Obsolete since Gecko 1.9 (Firefox 3)

setFolderTitle()

Note: setItemTitle() provides an alternative for this method.

Set the title for a bookmark folder.

void setFolderTitle(
  in PRInt64 folder,
  in AString title
);
Parameters
folder
The folder whose title should be set.
title
The new title for the folder.

Requires Gecko 1.9 (Firefox 3)

setItemDateAdded()

This method sets the date added time for an item.

void setItemDateAdded(
  in long long aItemId,
  in PRTime aDateAdded
);
Parameters
aItemId
The ID of the item whose added date time is to be set.
aDateAdded
The added date of the item.

Requires Gecko 1.9 (Firefox 3)

setItemGUID()

Obsolete since Gecko 14.0 (Firefox 14.0 / Thunderbird 14.0 / SeaMonkey 2.11)
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

This method sets a globally unique identifier. This can be useful when a sync algorithm deems two independently created items (on different profiles) to be the same item.

void setItemGUID(
  in long long aItemId,
  in AString aGUID
);
Parameters
aItemId
The ID of the item to set the GUID of.
aGUID
The GUID string.

Requires Gecko 1.9 (Firefox 3)

setItemIndex()

This method 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.

void setItemIndex(
  in long long aItemId,
  in long aNewIndex
);
Parameters
aItemId
The ID of the item to modify.
aNewIndex
The new index.
Exceptions thrown
 
If aNewIndex is out of bounds.

Requires Gecko 1.9 (Firefox 3)

setItemLastModified()

This method sets 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.

void setItemLastModified(
  in long long aItemId,
  in PRTime aLastModified
);
Parameters
aItemId
The ID of the item whose last modified time is to be set.
aLastModified
The last modified time of the item.

setItemTitle()

This method sets the title for an item.

void setItemTitle(
  in nsIURI uri, Obsolete since Gecko 1.9
  in long long aItemId, 
  in AUTF8String aTitle
);
Parameters
uri Obsolete since Gecko 1.9
The URI of the item whose title should be updated.
aItemId
The ID of the item whose title should be updated.
aTitle
The new title for the bookmark. Will be truncated to TITLE_LENGTH_MAX.

Requires Gecko 1.9 (Firefox 3)

setKeywordForBookmark()

This method 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.

void setKeywordForBookmark(
  in long long aItemId,
  in AString aKeyword
);
Parameters
aItemId
The item (bookmark) that needs to be associated with the keyword.
aKeyword
The keyword that needs to be associated with the item (bookmark).

Obsolete since Gecko 1.9 (Firefox 3)

setKeywordForURI()

Note: setKeywordForBookmark() provides an alternative for this method.

Associates the given keyword with the given URI.

Use an empty keyword to clear the keyword associated with the URI. Use an empty URI to clear the URI associated with that keyword. In both of these cases, succeeds but does nothing if the URL/keyword is not found.

When setting a keyword (both URI and keyword are specified), the URI must be bookmarked for the keyword to be persistent.

void setKeywordForURI(
  in nsIURI uri,
  in AString keyword
);
Parameters
uri
The URI of the bookmark.
keyword
The keyword that needs to be associated with the URI.

See also

Document Tags and Contributors

Contributors to this page: Dietrich, MKaply, Sheppy, trevorh, Arehman4, Nicoulas, Ancestor
Last updated by: Sheppy,