nsINavBookmarksService Interface Reference

import "nsINavBookmarksService.idl";

List of all members.

Public Member Functions

long long insertBookmark (in long long aParentFolder, in nsIURI aURI, in long aIndex, in AUTF8String aTitle)
void removeItem (in long long aItemId)
long long createFolder (in long long aParentFolder, in AUTF8String name, in long index)
long long createDynamicContainer (in long long aParentFolder, in AUTF8String 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 aItemId, in long long aNewParent, 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)
long long getIdForItemAt (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 AUTF8String aTitle)
AUTF8String 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)

Public Attributes

readonly attribute long long placesRoot
readonly attribute long long bookmarksMenuFolder
readonly attribute long long tagsFolder
readonly attribute long long unfiledBookmarksFolder
readonly attribute long long toolbarFolder
const short DEFAULT_INDEX = -1
const unsigned short TYPE_BOOKMARK = 1
const unsigned short TYPE_FOLDER = 2
const unsigned short TYPE_SEPARATOR = 3
const unsigned short TYPE_DYNAMIC_CONTAINER = 4

Detailed Description

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.

Definition at line 171 of file nsINavBookmarksService.idl.

Member Function Documentation

void nsINavBookmarksService::addObserver ( in nsINavBookmarkObserver  observer,
in boolean  ownsWeak 
)

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 nsINavBookmarksService::changeBookmarkURI ( in long long  aItemId,
in nsIURI  aNewURI 
)

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

long long nsINavBookmarksService::createDynamicContainer ( in long long  aParentFolder,
in AUTF8String  aName,
in AString  aContractId,
in long  aIndex 
)

Creates a dynamic container under the given parent folder.

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
Returns:
the ID of the newly-inserted folder

long long nsINavBookmarksService::createFolder ( in long long  aParentFolder,
in AUTF8String  name,
in long  index 
)

Creates a new child folder and inserts it under the given parent.

Parameters:
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
Returns:
the ID of the newly-inserted folder

nsIURI nsINavBookmarksService::getBookmarkedURIFor ( in nsIURI  aURI  ) 

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.

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

Returns the list of bookmark ids that contain the given URI.

void nsINavBookmarksService::getBookmarkIdsForURITArray ( in nsIURI  aURI,
in PRInt64Array  aResult 
)

TArray version of getBookmarksIdForURI 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.

nsIURI nsINavBookmarksService::getBookmarkURI ( in long long  aItemId  ) 

Get the URI for a bookmark item.

long long nsINavBookmarksService::getChildFolder ( in long long  aFolder,
in AString  aSubFolder 
)

Returns the ID of a child folder with the given name. This does not recurse, you have to give it an immediate sibling of the given folder. If the given subfolder doesn't exist, it will return 0.

Parameters:
aFolder Parent folder whose children we will search
aSubFolder Name of the folder to search for in folder

long long nsINavBookmarksService::getFolderIdForItem ( in long long  aItemId  ) 

Get the parent folder's id for an item.

boolean nsINavBookmarksService::getFolderReadonly ( in long long  aFolder  ) 

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.

Parameters:
aFolder the item-id of the folder.

long long nsINavBookmarksService::getIdForItemAt ( in long long  aFolder,
in long  aIndex 
)

Get the itemId given the containing folder and the index.

Parameters:
aFolder The direct parent folder of the item
aIndex The index of the item within aFolder, DEFAULT_INDEX for the last item
Returns:
the id of the found item
Exceptions:
if the item does not exist

PRTime nsINavBookmarksService::getItemDateAdded ( in long long  aItemId  ) 

Get the date added time for an item.

AString nsINavBookmarksService::getItemGUID ( in long long  aItemId  ) 

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

Parameters:
aItemId The ID of the item to get the GUID for
Returns:
The GUID string

long long nsINavBookmarksService::getItemIdForGUID ( in AString  aGUID  ) 

Get the ID of the item with the given GUID.

Parameters:
aGUID The GUID string of the item to search for
Returns:
The item ID, or -1 if not found

long nsINavBookmarksService::getItemIndex ( in long long  aItemId  ) 

Get the index for an item.

PRTime nsINavBookmarksService::getItemLastModified ( in long long  aItemId  ) 

Get the last modified time for an item.

AUTF8String nsINavBookmarksService::getItemTitle ( in long long  aItemId  ) 

Get the title for an item.

If no item title is available it will return a void string (null in JS).

Parameters:
aItemId The id of the item whose title should be retrieved
Returns:
The title of the item.

unsigned short nsINavBookmarksService::getItemType ( in long long  aItemId  ) 

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

AString nsINavBookmarksService::getKeywordForBookmark ( in long long  aItemId  ) 

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

AString nsINavBookmarksService::getKeywordForURI ( in nsIURI  aURI  ) 

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

nsITransaction nsINavBookmarksService::getRemoveFolderTransaction ( in long long  aFolder  ) 

Gets an undo-able transaction for removing a folder from the bookmarks tree.

Parameters:
folder The id of the folder to remove.
Returns:
An object implementing nsITransaction that can be used to undo or redo the action.
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.

nsIURI nsINavBookmarksService::getURIForKeyword ( in AString  keyword  ) 

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

long long nsINavBookmarksService::insertBookmark ( in long long  aParentFolder,
in nsIURI  aURI,
in long  aIndex,
in AUTF8String  aTitle 
)

Inserts a child bookmark into the given folder.

Parameters:
aParentFolder 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
Returns:
The ID of the newly-created bookmark

long long nsINavBookmarksService::insertSeparator ( in long long  aFolder,
in long  aIndex 
)

Inserts a bookmark separator into the given folder at the given index. The separator can be removed using removeChildAt().

Parameters:
aFolder Parent folder of the separator
aIndex The separator's index under folder, or DEFAULT_INDEX to append
Returns:
the id of the new separator

boolean nsINavBookmarksService::isBookmarked ( in nsIURI  aURI  ) 

Returns true if the given URI is in any bookmark folder. If you want the results to be redirect-aware, use getBookmarkedURIFor()

void nsINavBookmarksService::moveItem ( in long long  aItemId,
in long long  aNewParent,
in long  aIndex 
)

Moves an item to a different container, preserving its contents.

Parameters:
aItemId The id of the item to move
aNewParent The id of the new parent
aIndex The index under aNewParent, or DEFAULT_INDEX to append
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 nsINavBookmarksService::removeChildAt ( in long long  aFolder,
in long  aIndex 
)

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

Parameters:
aFolder The folder to remove a child from
aIndex The index of the child to remove

void nsINavBookmarksService::removeFolder ( in long long  aFolder  ) 

Removes a folder from the bookmarks tree.

NOTE: This API is deprecated. The correct method to use is removeItem. This will be removed in the next release after Firefox 3.0. The removal is in bug 428558.

Parameters:
aFolder The id of the folder to remove.

void nsINavBookmarksService::removeFolderChildren ( in long long  aFolder  ) 

Convenience function for container services. Removes all children of the given folder.

Parameters:
aFolder The id of the folder to remove children from.

void nsINavBookmarksService::removeItem ( in long long  aItemId  ) 

Removes a child item. Used to delete a bookmark or separator.

Parameters:
aItemId The child item to remove

void nsINavBookmarksService::removeObserver ( in nsINavBookmarkObserver  observer  ) 

Removes a bookmark observer.

void nsINavBookmarksService::runInBatchMode ( in nsINavHistoryBatchCallback  aCallback,
in nsISupports  aUserData 
)

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.

Parameters:
aCallback nsINavHistoryBatchCallback interface to call.
aUserData Opaque parameter passed to nsINavBookmarksBatchCallback

void nsINavBookmarksService::setFolderReadonly ( in long long  aFolder,
in boolean  aReadOnly 
)

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.

Parameters:
aFolder the item-id of the folder.
aReadOnly the read-only state (boolean).

void nsINavBookmarksService::setItemDateAdded ( in long long  aItemId,
in PRTime  aDateAdded 
)

Set the date added time for an item.

void nsINavBookmarksService::setItemGUID ( in long long  aItemId,
in AString  aGUID 
)

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

Parameters:
aItemId The id of the item to set the GUID of
aGUID The GUID string

void nsINavBookmarksService::setItemIndex ( in long long  aItemId,
in long  aNewIndex 
)

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.

Parameters:
aItemId The id of the item to modify
aNewIndex The new index

void nsINavBookmarksService::setItemLastModified ( in long long  aItemId,
in PRTime  aLastModified 
)

Set the last modified time for an item.

void nsINavBookmarksService::setItemTitle ( in long long  aItemId,
in AUTF8String  aTitle 
)

Set the title for an item.

Parameters:
aItemId The id of the item whose title should be updated
aTitle The new title for the bookmark.

void nsINavBookmarksService::setKeywordForBookmark ( in long long  aItemId,
in AString  aKeyword 
)

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.

Member Data Documentation

readonly attribute long long nsINavBookmarksService::bookmarksMenuFolder

The item ID of the bookmarks menu folder.

Definition at line 181 of file nsINavBookmarksService.idl.

const short nsINavBookmarksService::DEFAULT_INDEX = -1

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.

Definition at line 203 of file nsINavBookmarksService.idl.

readonly attribute long long nsINavBookmarksService::placesRoot

The item ID of the Places root.

Definition at line 176 of file nsINavBookmarksService.idl.

readonly attribute long long nsINavBookmarksService::tagsFolder

The item ID of the top-level folder that contain the tag "folders".

Definition at line 186 of file nsINavBookmarksService.idl.

readonly attribute long long nsINavBookmarksService::toolbarFolder

The item ID of the personal toolbar folder.

Definition at line 196 of file nsINavBookmarksService.idl.

const unsigned short nsINavBookmarksService::TYPE_BOOKMARK = 1

Definition at line 205 of file nsINavBookmarksService.idl.

const unsigned short nsINavBookmarksService::TYPE_DYNAMIC_CONTAINER = 4

Definition at line 208 of file nsINavBookmarksService.idl.

const unsigned short nsINavBookmarksService::TYPE_FOLDER = 2

Definition at line 206 of file nsINavBookmarksService.idl.

const unsigned short nsINavBookmarksService::TYPE_SEPARATOR = 3

Definition at line 207 of file nsINavBookmarksService.idl.

readonly attribute long long nsINavBookmarksService::unfiledBookmarksFolder

The item ID of the unfiled-bookmarks folder.

Definition at line 191 of file nsINavBookmarksService.idl.

The documentation for this interface was generated from the following file:
Generated on Fri Jan 16 21:13:03 2009 for Places by  doxygen 1.5.8