nsINavHistoryObserver

Method overview

Constants

Methods

The specified page and all its visits are about to be deleted.

Delete notifications aren't quite 100% accurate. Batch delete operations take place in two steps; the notifications come first, followed by a bulk delete. If an error occurs in between these two steps (for example, an out of memory error), then you may get a notification even though the page doesn't wind up getting deleted.

void onBeforeDeleteURI(
  in nsIURI aURI,
  in ACString aGUID
);

Parameters

aURI

The URI of the page about to be deleted.

aGUID

The unique ID associated with the page.

onBeginUpdateBatch()

Notifies you that a batch of things are about to change. You should avoid doing any heavy-duty processing until onEndUpdateBatch() is called.

void onBeginUpdateBatch();

Parameters

None.

onClearHistory()

Called just prior to all of history being cleared.

void onClearHistory();

Parameters

None.

onDeleteURI()

The specified page and all its visits has been deleted.

Delete notifications are not quite 100% accurate. Batch delete operations take place in two steps; the notifications come first, followed by a bulk delete. If an error occurs in between these two steps (for example, an out of memory error), then you may get a notification even though the page doesn't wind up getting deleted.

Notes

The removePagesByHost() and removePagesByTimeFrame() functions call beginUpdateBatch() and endUpdateBatch() rather than onClearHistory() or onDeleteURI().

void onDeleteURI(
  in nsIURI aURI,
  in ACString aGUID
);

Parameters

aURI

The URI of the page that was deleted.

aGUID

The unique ID associated with the page.

Called when some visits of an history entry are expired.

void onDeleteVisits(
  in nsIURI aURI,
  in PRTime aVisitTime,
  in ACString aGUID
);

Parameters

aURI

The URI of the page whose visits have been expired.

aVisitTime

The largest visit time in microseconds that has been expired. We guarantee that we do not have any visit older than this date.

aGUID

The unique ID associated with the page.

onEndUpdateBatch()

Called once a batch of updates is completed. Once this has been called, you can perform processing, user interface updates, and so forth. This is called sometime after onBeginUpdateBatch().

void onEndUpdateBatch();

Parameters

None.

onPageChanged()

Some attribute on the specified page has changed.

Note that for TYPED and HIDDEN pages, the page might not actually have been added yet. This needs to be clarified; what are TYPED and HIDDEN?

void onPageChanged(
  in nsIURI aURI,
  in unsigned long aWhat,
  in AString aValue
);

Parameters

aURI

The URI of the page on which an attribute changed.

aWhat

The attribute whose value changed.

aValue

The attribute's new value.

Called when a history entry expires. This notification is sent to indicate that a specific visit has expired, and includes the time of that visit. When the last visit for a history entry expires, the history entry itself is deleted and the aWholeEntry parameter is true.

If your code only cares about whole entries being deleted instead of individual visits, you can simply act only when aWholeEntry is true.

It's possible for a history entry to be deleted even though it has no visits if something is out of sync after a bookmark with no visits is deleted; this results in the entire history entry being freed). In such cases, aVisitTime is 0.

void onPageExpired(
  in nsIURI aURI,
  in PRTime aVisitTime,
  in boolean aWholeEntry
);

Parameters

aURI

The URI of the page that expired.

aVisitTime

The visit time that expired; this may (or may not) be 0 if a bookmark with no visits is deleted.

aWholeEntry

true if this expiration will result in the entire history entry being deleted from the history store; if false, only the specified visit is being deleted.

onTitleChanged()

Called whenever either the real title or the custom title of the page changes. Both titles are always included in this notification, even though only one is changed each time it is called, since often consumers will want to display the user title if available, falling back to the title specified by the page's <title> element if there is no user title.

It's important to note that there is a difference between an empty title and a null title. An empty string means the title was specifically set to be nothing. null means the title was not set at all. From C++ code, use the IsVoid() and SetIsvoid() methods to see whether an empty string is "null" or not; in either case it will always be an empty string.

void onTitleChanged(
  in nsIURI aURI,
  in AString aPageTitle
);

Parameters

aURI

The URI of the page whose title changed.

aPageTitle

The new title of the page.

Called when a resource is visited. This is called the first time a resource (page, image, and so on.) is seen as well as every subsequent time.

Normally, transition types of TRANSITION_EMBED (corresponding to images in a page, for example) are not displayed in history results (unless includeHidden is set). Many observers can ignore _EMBED notifications (which will comprise the majority of visit notifications) to save work.

void onVisit(
  in nsIURI aURI,
  in long long aVisitID,
  in PRTime aTime,
  in long long aSessionID,
  in long long aReferringID,
  in unsigned long aTransitionType,
  in ACString aGUID,
  out unsigned long aAdded
);

Parameters

aURI

The URI of the page being visited.

aVisitID

ID of the visit that was just created.

aTime

Time of the visit.

aSessionID

The ID of one connected sequence of visits.

aReferringID

The ID of the visit the user came from. 0 if empty.

aTransitionType

The type of the item that is about to be removed; this is one of the nsINavBookmarksService.Constants defined in the nsINavBookmarksService interface.

aGUID

The unique ID associated with the page.

aAdded

Incremented by query nodes when the visited uri belongs to them. If no such query exists, the history result creates a new query node dynamically. It is used in places views only and can be ignored.

Using onBeforeDeleteURI() in Gecko 1.9.1

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

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

See also

• nsINavHistoryResult