nsINavBookmarksService

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

Attributes

Constants

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).

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.

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.

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.

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".

nsIURI getBookmarkedURIFor(
  in nsIURI aURI
);

Parameters

aURI

The URI that needs to be checked if it is bookmarked or not.

Return value

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

getItemGUID()

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.

getItemIdForGUID()

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.

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.

getItemLastModified()

This method retrieves the last modified time for an item.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

moveItem()

This method moves an item to a different container, preserving its contents.

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.

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.

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.

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.

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.

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.

void setFolderReadonly(
  in long long aFolder,
  in boolean aReadOnly
);

Parameters

aFolder

The item-id of the folder.

aReadOnly

The read-only state.

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.

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.

setItemGUID()

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.

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.

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.

setItemLastModified()

This method sets the last modified time for an item.

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.

setKeywordForBookmark()

Obsolete since Gecko 40.0

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).

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

• Places
• Manipulating bookmarks using Places
• nsITransaction
• nsINavBookmarkObserver
• nsINavHistoryBatchCallback