toolkit/components/places/nsINavBookmarksService.idlScriptable
This interface is an observer for bookmark changes.
1.0
66
Introduced
Gecko 1.8
Inherits from: nsISupports Last changed in Gecko 21.0 (Firefox 21.0 / Thunderbird 21.0 / SeaMonkey 2.18)

Method overview

void onBeforeItemRemoved(in long long aItemId, in unsigned short aItemType, in long long aParentId, in ACString aGUID, in ACString aParentGUID); Obsolete since Gecko 21.0
void onBeginUpdateBatch();
void onEndUpdateBatch();
void onFolderAdded(in PRInt64 folder, in PRInt64 parent, in PRInt32 index); Obsolete since Gecko 1.9
void onFolderChanged(in PRInt64 folder, in ACString property); Obsolete since Gecko 1.9
void onFolderMoved(in PRInt64 folder, in PRInt64 oldParent, in PRInt32 oldIndex, in PRInt64 newParent, in PRInt32 newIndex); Obsolete since Gecko 1.9
void onFolderRemoved(in PRInt64 folder, in PRInt64 parent, in PRInt32 index); Obsolete since Gecko 1.9
void onItemAdded(in long long aItemId, in long long aParentId, in long aIndex, in unsigned short aItemType, in nsIURI aURI, in AUTF8String aTitle, in PRTime aDateAdded, in ACString aGUID, in ACString aParentGUID);
void onItemChanged(in long long aItemId, in ACString aProperty, in boolean aIsAnnotationProperty, in AUTF8String aNewValue, in PRTime aLastModified, in unsigned short aItemType, in long long aParentId, in ACString aGUID, in ACString aParentGUID);
void onItemMoved(in long long aItemId, in long long aOldParentId, in long aOldIndex, in long long aNewParentId, in long aNewIndex, in unsigned short aItemType, in ACString aGUID, in ACString aOldParentGUID, in ACString aNewParentGUID);
void onItemRemoved(in long long aItemId, in long long aParentId, in long aIndex, in unsigned short aItemType, in nsIURI aURI, in ACString aGUID, in ACString aParentGUID);
void onItemReplaced(in PRInt64 folder, in nsIURI item, in nsIURI newItem); Obsolete since Gecko 1.9
void onItemVisited(in long long aItemId, in long long aVisitId, in PRTime aTime, in unsigned long aTransitionType, in nsIURI aURI, in long long aParentId, in ACString aGUID, in ACString aParentGUID);
void onSeparatorAdded(in PRInt64 parent, in PRInt32 index); Obsolete since Gecko 1.9
void onSeparatorRemoved(in PRInt64 parent, in PRInt32 index); Obsolete since Gecko 1.9

Methods

onBeforeItemRemoved()

Obsolete since Gecko 21.0 (Firefox 21.0 / Thunderbird 21.0 / SeaMonkey 2.18)

Note: This method was removed in Gecko 21.0 as part of Bug 826409.

This method notifies this observer that an item is about to be removed. It is called before the actual removal takes place.

void onBeforeItemRemoved(
  in long long aItemId,
  in unsigned short aItemType,
  in long long aParentId,
  in ACString aGUID,
  in ACString aParentGUID
);
Parameters
aItemId
The id of the bookmark that will be removed.
aItemType
The type of the item that is about to be removed; this is one of the nsINavBookmarksService.Type constants.
aParentId
The id of the folder containing the item.
aGUID
The unique ID associated with the item.
aParentGUID
The unique ID associated with the item's parent.

onBeginUpdateBatch()

This method notifies this observer that a batch transaction has started. Other notifications will be sent during the batch change, but the observer is guaranteed that onEndUpdateBatch() will be called at the completion of changes. During a batch the observer should do its best to reduce the work done to handle notifications, since multiple changes are going to happen in a short timeframe.

void onBeginUpdateBatch();
Parameters

None.

onEndUpdateBatch()

This method notifies this observer that a batch transaction has ended.

void onEndUpdateBatch();
Parameters

None.

onFolderAdded()

Obsolete since Gecko 1.9 (Firefox 3)

Notify this observer that a bookmark folder has been added.

void onFolderAdded(
  in PRInt64 folder,
  in PRInt64 parent,
  in PRInt32 index
);
Parameters
folder
The id of the folder that was added.
parent
The id of the folder's parent.
index
The folder's index inside its parent.

onFolderChanged()

Obsolete since Gecko 1.9 (Firefox 3)

Notify this observer that a bookmark folder's information has changed. This will be called whenever any attributes like "title" are changed.

void onFolderChanged(
  in PRInt64 folder,
  in ACString property
);
Parameters
folder
The id of the folder that was changed.
property
The property that was changed.

onFolderMoved()

Obsolete since Gecko 1.9 (Firefox 3)

Notify this observer that a bookmark folder has been moved.

void onFolderMoved(
  in PRInt64 folder,
  in PRInt64 oldParent,
  in PRInt32 oldIndex,
  in PRInt64 newParent,
  in PRInt32 newIndex
);
Parameters
folder
The id of the folder that was moved.
oldParent
The id of the folder's old parent.
oldIndex
The folder's old index inside oldParent.
newParent
The id of the folder's new parent.
newIndex
The folder's index inside newParent.

onFolderRemoved()

Obsolete since Gecko 1.9 (Firefox 3)

Notify this observer that a bookmark folder has been removed.

void onFolderRemoved(
  in PRInt64 folder,
  in PRInt64 parent,
  in PRInt32 index
);
Parameters
folder
The id of the folder that was removed.
parent
The id of the folder's old parent.
index
The folder's old index in its parent.

onItemAdded()

This method notifies this observer that an item was added. It is called after the actual addition took place. When a new item is created, all the items following it in the same folder will have their index shifted down, but no additional notifications will be sent.

void onItemAdded(
  in long long aItemId,
  in long long aParentId,
  in long aIndex,
  in unsigned short aItemType,
  in nsIURI aURI,
  in AUTF8String aTitle,
  in PRTime aDateAdded,
  in ACString aGUID,
  in ACString aParentGUID
);
Parameters
aItemId
The id of the item that was added.
aParentId
The id of the folder to which the item was added.
aIndex
The item's index in the folder.
aItemType
The type of the item that was added. This should be one of the nsINavBookmarksService.Type constants.
aURI
The URI of the item that was added when aItemType is TYPE_BOOKMARK, null otherwise.
aTitle
The title of the added item.
aDateAdded
The stored date added value, in microseconds from the epoch.
aGUID
The unique ID associated with the item.
aParentGUID
The unique ID associated with the item's parent.

onItemChanged()

This method notifies this observer that an item's information has changed. It is called whenever any attributes like "title" are changed.

void onItemChanged(
  in long long aItemId,
  in ACString aProperty,
  in boolean aIsAnnotationProperty,
  in AUTF8String aNewValue,
  in PRTime aLastModified,
  in unsigned short aItemType,
  in long long aParentId,
  in ACString aGUID,
  in ACString aParentGUID
);
Parameters
aItemId
The id of the item that was changed.
aProperty
The property which changed. If this string is empty, all properties have been deleted. In this situation, you should not attempt to get any properties, since this will result in the automatic regeneration of properties that will then be leaked into the database, causing trouble later.
aIsAnnotationProperty
Indicates whether or not aProperty is the name of an item annotation. If this is true, aNewValue is always an empty string.
aNewValue
The items new value, if required by the property specified by aProperty.
aLastModified
The value to set the items last modified time to, or 0 if the value should remain unchanged.
aItemType
The type of the item that has been changed. This should be one of the nsINavBookmarksService.Type constants.
aParentId
The id of the folder containing the item.
aGUID
The unique ID associated with the item.
aParentGUID
The unique ID associated with the item's parent.
Notes

This table indicates what aNewValue should be depending on property specified by aProperty:

Property string Value
"cleartime" Empty string; this property means the history was deleted, so there's no last visit date.
"title" The new title for the item
"favicon" The "moz-anno" URL for the new favicon image.
"uri" The new URI for the item.
"tags" Empty string; this property indicates that the set of tags for the item have changed.
"dateAdded" The PRTime at which the item was first added to the database.
"lastModified" The PRTime at which the item was last modified.

onItemMoved()

This method notifies this observer that an item has been moved.

void onItemMoved(
  in long long aItemId,
  in long long aOldParentId,
  in long aOldIndex,
  in long long aNewParentId,
  in long aNewIndex,
  in unsigned short aItemType,
  in ACString aGUID,
  in ACString aOldParentGUID,
  in ACString aNewParentGUID
);
Parameters
aItemId
The id of the item that was moved.
aOldParentId
The id of the old parent.
aOldIndex
The old index inside aOldParentId.
aNewParentId
The id of the new parent.
aNewIndex
The new index inside aNewParentId.
aItemType
The type of the item that was moved. This should be one of the nsINavBookmarksService.Type constants.
aGUID
The unique ID associated with the item.
aOldParentGUID
The unique ID associated with the old item's parent.
aNewParentGUID
The unique ID associated with the new item's parent.

onItemRemoved()

This method notifies that an item was removed. It is called after the actual remove took place. When an item is removed, all the items following it in the same folder will have their index shifted down, but no additional notifications will be sent.

void onItemRemoved(
  in long long aItemId,
  in long long aParentId,
  in long aIndex,
  in unsigned short aItemType,
  in nsIURI aURI,
  in ACString aGUID,
  in ACString aParentGUID
);
Parameters
aItemId
The ID of the item that was removed.
aParentId
The ID of the folder from which the item was removed.
aIndex
The index of the item that was removed from the folder.
aItemType
The type of the item that was removed. This should be one of the nsINavBookmarksService.Type constants.
aURI
The URI of the added item if it was TYPE_BOOKMARK, null otherwise.
aGUID
The unique ID associated with the item.
aParentGUID
The unique ID associated with the item's parent.

onItemReplaced()

Obsolete since Gecko 1.9 (Firefox 3)

Notify this observer that a bookmark has been replaced.

void onItemReplaced(
  in PRInt64 folder,
  in nsIURI item,
  in nsIURI newItem
);
Parameters
folder
The folder in which the bookmark was replaced.
item
The item which was replaced.
newItem
The new item which replaced item.

onItemVisited()

This method notifies that the item was visited. Can be invoked only for TYPE_BOOKMARK items.

Normally in bookmarks we use the last visit date, and normally the time will be a new visit that will be more recent, but this is not guaranteed. You should check to see if it is actually more recent before using this new time.

See onItemChanged() method property = "cleartime" for when all visit dates are deleted for the URI.

Note: The reported time is the time of the visit that was added, which may be well in the past since the visit time can be specified. This means that the visit the observer is told about may not be the most recent visit for that page.

void onItemVisited(
  in long long aItemId,
  in long long aVisitId,
  in PRTime aTime,
  in unsigned long aTransitionType,
  in nsIURI aURI,
  in long long aParentId,
  in ACString aGUID,
  in ACString aParentGUID
);
Parameters
aItemId
The id of the bookmark that was visited.
aVisitId
The id of the item visit.
aTime
The time of the visit.
aTransitionType
The transition for the visit. See nsINavBookmarksService.Transaction constants for a list of possible values.
aURI
The nsIURI for this bookmark.
aParentId
The id of the folder containing the item.
aGUID
The unique ID associated with the item.
aParentGUID
The unique ID associated with the item's parent.

onSeparatorAdded()

Obsolete since Gecko 1.9 (Firefox 3)

Notify this observer that a separator has been added.

void onSeparatorAdded(
  in PRInt64 parent,
  in PRInt32 index
);
Parameters
parent
The id of the separator's parent.
index
The separator's index inside its parent.

onSeparatorRemoved()

Obsolete since Gecko 1.9 (Firefox 3)

Notify this observer that a separator has been removed.

void onSeparatorRemoved(
  in PRInt64 parent,
  in PRInt32 index
);
Parameters
parent
The id of the separator's parent.
index
The separator's old index in its parent.

Using onBeforeItemRemoved() in Gecko 1.9.1

If you wish to support onBeforeItemRemoved() in applications based on Gecko 1.9.1, you must implement your observer's QueryInterface() method to match on both nsINavBookmarkObserver and nsINavBookmarkObserver_MOZILLA_1_9_1_ADDITIONS, as shown below.

QueryInterface: function(iid) {
  if (iid.equals(Ci.nsINavBookmarkObserver) ||
      iid.equals(Ci.nsINavBookmarkObserver_MOZILLA_1_9_1_ADDITIONS) ||
      iid.equals(Ci.nsISupports)) {
    return this;
  }
  throw Cr.NS_ERROR_NO_INTERFACE;
}

See also