nsINavBookmarksService

From MDC

The nsINavBookmarksService 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.

Contents 1 Method overview 2 Attributes 3 Constants 4 Methods 4.1 insertBookmark() 4.1.1 Parameters 4.1.2 Return value 4.2 removeItem() 4.2.1 Parameters 4.3 createFolder() 4.3.1 Parameters 4.3.2 Return value 4.4 createDynamicContainer() 4.4.1 Parameters 4.4.2 Return value 4.5 removeFolder() 4.5.1 Parameters 4.6 getRemoveFolderTransaction() 4.6.1 Parameters 4.6.2 Return value 4.7 removeFolderChildren() 4.7.1 Parameters 4.8 moveItem() 4.8.1 Parameters 4.9 getChildFolder() 4.9.1 Parameters 4.9.2 Return value 4.10 insertSeparator() 4.10.1 Parameters 4.10.2 Return value 4.11 removeChildAt() 4.11.1 Parameters 4.12 getItemGUID() 4.12.1 Parameters 4.12.2 Return value 4.13 setItemGUID() 4.13.1 Parameters 4.14 getItemIdForGUID() 4.14.1 Parameters 4.14.2 Return value 4.15 setItemTitle() 4.15.1 Parameters 4.16 getItemTitle() 4.16.1 Parameters 4.16.2 Return value 4.17 setItemDateAdded() 4.17.1 Parameters 4.18 getItemDateAdded() 4.18.1 Parameters 4.18.2 Return value 4.19 setItemLastModified() 4.19.1 Parameters 4.20 getItemLastModified() 4.20.1 Parameters 4.20.2 Return value 4.21 getBookmarkURI() 4.21.1 Parameters 4.21.2 Return value 4.22 getItemIndex() 4.22.1 Parameters 4.22.2 Return value 4.23 setItemIndex() 4.23.1 Parameters 4.24 getItemType() 4.24.1 Parameters 4.24.2 Return value 4.25 getFolderReadonly() 4.25.1 Parameters 4.25.2 Return value 4.26 setFolderReadonly() 4.26.1 Parameters 4.27 isBookmarked() 4.27.1 Parameters 4.27.2 Return value 4.28 getBookmarkedURIFor() 4.28.1 Parameters 4.28.2 Return value 4.29 changeBookmarkURI() 4.29.1 Parameters 4.30 getFolderIdForItem() 4.30.1 Parameters 4.30.2 Return value 4.31 getBookmarkIdsForURI() 4.31.1 Parameters 4.32 getBookmarkIdsForURITArray() 4.32.1 Parameters 4.33 setKeywordForBookmark() 4.33.1 Parameters 4.34 getKeywordForURI() 4.34.1 Parameters 4.34.2 Return value 4.35 getKeywordForBookmark() 4.35.1 Parameters 4.35.2 Return value 4.36 getURIForKeyword() 4.36.1 Parameters 4.36.2 Return value 4.37 addObserver() 4.37.1 Parameters 4.38 removeObserver() 4.38.1 Parameters 4.39 runInBatchMode() 4.39.1 Parameters 4.40 See also

nsINavBookmarksService is defined in toolkit/components/places/public/nsINavBookmarksService.idl. It is scriptable and unfrozen (hasn't changed since Mozilla 1.9).

Inherits from: nsISupports

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

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

[edit] Method overview

long long insertBookmark(in long long aParentFolder, in nsIURI aURI, in long aIndex, in AString aTitle);

void removeItem(in long long aItemId);

long long createFolder(in long long aParentFolder, in AString name, in long index);

long long createDynamicContainer(in long long aParentFolder, in AString aName, in AString aContractId, in long aIndex);

void removeFolder(in long long aFolder);

nsITransaction getRemoveFolderTransaction(in long long aFolder);

void removeFolderChildren(in long long aFolder);

void moveItem(in long long aFolder, in long long newParent, in long aIndex);

long long getChildFolder(in long long aFolder, in AString aSubFolder);

long long insertSeparator(in long long aFolder, in long aIndex);

void removeChildAt(in long long aFolder, in long aIndex);

AString getItemGUID(in long long aItemId);

void setItemGUID(in long long aItemId, in AString aGUID);

long long getItemIdForGUID(in AString aGUID);

void setItemTitle(in long long aItemId, in AString aTitle);

AString getItemTitle(in long long aItemId);

void setItemDateAdded(in long long aItemId, in PRTime aDateAdded);

PRTime getItemDateAdded(in long long aItemId);

void setItemLastModified(in long long aItemId, in PRTime aLastModified);

PRTime getItemLastModified(in long long aItemId);

nsIURI getBookmarkURI(in long long aItemId);

long getItemIndex(in long long aItemId);

void setItemIndex(in long long aItemId, in long aNewIndex);

unsigned short getItemType(in long long aItemId);

boolean getFolderReadonly(in long long aFolder);

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

boolean isBookmarked(in nsIURI aURI);

nsIURI getBookmarkedURIFor(in nsIURI aURI);

void changeBookmarkURI(in long long aItemId, in nsIURI aNewURI);

long long getFolderIdForItem(in long long aItemId);

void getBookmarkIdsForURI(in nsIURI aURI, out unsigned long count, [array, retval, size_is(count)] out long long bookmarks);

void getBookmarkIdsForURITArray(in nsIURI aURI, in PRInt64Array aResult);

void setKeywordForBookmark(in long long aItemId, in AString aKeyword);

AString getKeywordForURI(in nsIURI aURI);

AString getKeywordForBookmark(in long long aItemId);

nsIURI getURIForKeyword(in AString keyword);

void addObserver(in nsINavBookmarkObserver observer, in boolean ownsWeak);

void removeObserver(in nsINavBookmarkObserver observer);

void runInBatchMode(in nsINavHistoryBatchCallback aCallback, in nsISupports aUserData);

[edit] Attributes

Attribute	Type	Description
placesRoot	long long	The folder 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.
bookmarksMenuFolder	long long	The item ID of the Bookmarks Menu folder.
tagsFolder	long long	The item ID of the top-level folder that contains the tag "folders".
unfiledBookmarksFolder	long long	The item ID of the Unfiled Bookmarks folder.
toolbarFolder	long long	The item ID of the personal toolbar folder.

[edit] Constants

Constant	Value	Description
DEFAULT_INDEX	-1	This is the default index.
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".

[edit] Methods

[edit] insertBookmark()

This method inserts a child bookmark into the given folder.

 long long insertBookmark(
   in long long aParentFolder, 
   in nsIURI aURI,
   in long aIndex, 
   in AString aTitle
 );

[edit] Parameters

aParentFolder

The ID of the parent folder.

aURI

The URI to insert.

aIndex

The index to insert at, or -1 to append to the end of the list.

aTitle

The title for the new bookmark.

[edit] Return value

Returns the ID of the newly-created bookmark.

[edit] removeItem()

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

 void removeItem(
   in long long aItemId
 );

[edit] Parameters

removeItem

The child item to remove.

[edit] createFolder()

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

 long long createFolder(
   in long long aParentFolder, 
   in AString name,
   in long index
 );

[edit] Parameters

aParentFolder

The ID of the parent folder.

name

The name of the new folder.

index

The index to insert at, or -1 to append to the end of the list.

[edit] Return value

Returns the ID of the newly-inserted folder.

[edit] createDynamicContainer()

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

 long long createDynamicContainer(
   in long long aParentFolder, 
   in AString aName,
   in AString aContractId, 
   in long aIndex
 );

[edit] 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 -1 to append to the end of the list.

[edit] Return value

Returns the ID of the newly-inserted folder.

[edit] removeFolder()

This method removes a folder from the bookmarks tree.

 void removeFolder(
   in long long aFolder
 );

[edit] Parameters

aFolder

The ID of the folder to remove.

[edit] 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 aFolder
 );

[edit] Parameters

aFolder

The ID of the folder to remove.

[edit] Return value

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

[edit] removeFolderChildren()

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

 void removeFolderChildren(
   in long long aFolder
 );

[edit] Parameters

aFolder

The ID of the folder to remove children from.

[edit] moveItem()

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

 void moveItem(
   in long long aFolder, 
   in long long newParent, 
   in long aIndex
 );

[edit] Parameters

aFolder

The ID of the item to move.

newParent

The ID of the new parent.

aIndex

The index to insert at, or "-1" to append to the end of the list.

[edit] 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
 );

[edit] Parameters

aFolder

Parent folder whose children we will search.

aSubFolder

Name of the folder to search for in folder.

[edit] Return value

Returns the ID of a child folder with the given name. If the given subfolder doesn't exist, it will return "0".

[edit] insertSeparator()

This method inserts a bookmark separator into the given folder at the given index. The separator can be removed using removeChildAt method.

 long long insertSeparator(
   in long long aFolder, 
   in long aIndex
 );

[edit] Parameters

aFolder

Parent folder of the separator.

aIndex

The separator's index under the folder, or "-1" to append to the end of the list.

[edit] Return value

Returns the ID of the new separator.

[edit] removeChildAt()

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

 void removeChildAt(
   in long long aFolder, 
   in long aIndex
 );

[edit] Parameters

aFolder

The folder to remove a child from.

aIndex

The index of the child to remove.

[edit] 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
 );

[edit] Parameters

aItemId

The ID of the item to get the GUID for.

[edit] Return value

Returns the GUID string.

[edit] 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
 );

[edit] Parameters

aItemId

The ID of the item to set the GUID of.

aGUID

The GUID string.

[edit] getItemIdForGUID()

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

 long long getItemIdForGUID(
   in AString aGUID
 );

[edit] Parameters

aGUID

The GUID string of the item to search for.

[edit] Return value

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

[edit] setItemTitle()

This method sets the title for an item.

 void setItemTitle(
   in long long aItemId, 
   in AString aTitle
 );

[edit] Parameters

aItemId

The ID of the item whose title should be updated.

aTitle

The new title for the bookmark.

[edit] 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).

 AString getItemTitle(
   in long long aItemId
 );

[edit] Parameters

aItemId

The ID of the item whose title should be retrieved.

[edit] Return value

Returns the title of the item.

[edit] setItemDateAdded()

This method sets the date added time for an item.

 void setItemDateAdded(
   in long long aItemId, 
   in PRTime aDateAdded
 );

[edit] Parameters

aItemId

The ID of the item whose added date time is to be set.

aDateAdded

The added date of the item.

[edit] getItemDateAdded()

This method retrieves the date added time for an item.

 PRTime getItemDateAdded(
   in long long aItemId
 );

[edit] Parameters

aItemId

The ID of the item whose added date time is to be retrieved.

[edit] Return value

Returns the date added time for the given item.

[edit] setItemLastModified()

This method sets the last modified time for an item.

 void setItemLastModified(
   in long long aItemId, 
   in PRTime aLastModified
 );

[edit] Parameters

aItemId

The ID of the item whose last modified time is to be set.

aLastModified

The last modified time of the item.

[edit] getItemLastModified()

This method retrieves the last modified time for an item.

 PRTime getItemLastModified(
   in long long aItemId
 );

[edit] Parameters

aItemId

The ID of the item whose last modified time is to be retrieved.

[edit] Return value

Returns the last modified time for the given item.

[edit] getBookmarkURI()

This method retrieves the URI for a bookmark item.

 nsIURI getBookmarkURI(
   in long long aItemId
 );

[edit] Parameters

aItemId

The ID of the bookmark item whose URI is to be retrieved.

[edit] Return value

Returns a nsIURI representing the URI of the bookmark.

[edit] getItemIndex()

This method retrieves the index for an item.

 long getItemIndex(
   in long long aItemId
 );

[edit] Parameters

aItemId

The ID of the item whose index is to be retrieved.

[edit] Return value

Returns the index of the given item.

[edit] 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
 );

[edit] Parameters

aItemId

The ID of the item to modify.

aNewIndex

The new index.

[edit] 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
 );

[edit] Parameters

aItemId

The ID of the item whose type is to be retrieved.

[edit] Return value

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

[edit] 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 aFolder
 );

[edit] Parameters

aFolder

The item-id of the folder.

[edit] Return value

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

[edit] 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
 );

[edit] Parameters

aFolder

The item-id of the folder.

aReadOnly

The read-only state (boolean).

[edit] 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 method.

 boolean isBookmarked(
   in nsIURI aURI
 );

[edit] Parameters

aURI

The URI whose existence in any bookmark folder is needed to be checked.

[edit] Return value

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

[edit] 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
 );

[edit] Parameters

aURI

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

[edit] Return value

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

[edit] changeBookmarkURI()

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

 void changeBookmarkURI(
   in long long aItemId, 
   in nsIURI aNewURI
 );

[edit] Parameters

aItemId

The item whose bookmark URI needs to be changed.

aNewURI

The new URI.

[edit] getFolderIdForItem()

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

 long long getFolderIdForItem(
   in long long aItemId
 );

[edit] Parameters

aItemId

The item whose parent folder's ID is to retrieved.

[edit] Return value

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

[edit] getBookmarkIdsForURI()

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

 void getBookmarkIdsForURI(
   in nsIURI aURI, 
   out unsigned long count,
   [array, retval, size_is(count)] out long long bookmarks
 );

[edit] 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.

[edit] getBookmarkIdsForURITArray()

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

[edit] Parameters

aURI

The URI whose list of bookmark IDs is to be retrieved.

aResult

The list of bookmark IDs.

[edit] 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
 );

[edit] 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).

[edit] 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
 );

[edit] Parameters

aURI

The URI whose keyword is to be retrieved.

[edit] Return value

Returns the keyword for the given URI.

[edit] 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
 );

[edit] Parameters

aItemId

The item (bookmark) whose keyword is to be retrieved.

[edit] Return value

Returns the keyword for the given bookmark.

[edit] getURIForKeyword()

This method retrieves the URI associated with the given keyword.

 nsIURI getURIForKeyword(
   in AString keyword
 );

[edit] Parameters

keyword

The keyword whose URI is to be retrieved.

[edit] Return value

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

[edit] 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
 );

[edit] Parameters

observer

The bookmark observer to be added.

ownsWeak

The owning reference state (boolean).

[edit] removeObserver()

This method removes a bookmark observer.

 void removeObserver(
   in nsINavBookmarkObserver observer
 );

[edit] Parameters

observer

The bookmark observer to be removed.

[edit] runInBatchMode()

This method runs the passed callback in batch mode. Use this when a lot of things are about to change. Calls can be nested, observers will only be notified when all batches begin/end.

 void runInBatchMode(
   in nsINavHistoryBatchCallback aCallback,
   in nsISupports aUserData
 );

[edit] Parameters

aCallback

nsINavHistoryBatchCallback interface to call.

aUserData

Opaque parameter passed to nsINavBookmarksBatchCallback.

[edit] See also

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