nsIBrowserHistory

A browser-specific interface to global history. It adds functions used by the basic browser like, marking pages as typed in the URL bar, and removing pages as from the history interface.
Inherits from: nsIGlobalHistory2 Last changed in Gecko 22.0 (Firefox 22.0 / Thunderbird 22.0 / SeaMonkey 2.19)

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

var browserHistory = Components.classes["@mozilla.org/browser/nav-history-service;1"]
                     .getService(Components.interfaces.nsIBrowserHistory);

Method overview

void addPageWithDetails(in nsIURI aURI, in wstring aTitle, in long long aLastVisited); Obsolete since Gecko 15.0
void markPageAsFollowedLink(in nsIURI aURI); Obsolete since Gecko 22.0
void markPageAsTyped(in nsIURI aURI); Obsolete since Gecko 22.0
void registerOpenPage(in nsIURI aURI); Obsolete since Gecko 9.0
void removeAllPages();
void removePage(in nsIURI aURI);
void removePages([array, size_is(aLength)] in nsIURI aURIs, in unsigned long aLength, in boolean aDoBatchNotify);
void removePagesByTimeframe(in long long aBeginTime, in long long aEndTime);
void removePagesFromHost(in AUTF8String aHost, in boolean aEntireDomain);
void removeVisitsByTimeframe(in long long aBeginTime, in long long aEndTime);
void unregisterOpenPage(in nsIURI aURI); Obsolete since Gecko 9.0
Note: The markPageAsFollowedLink and markPageAsTyped methods were moved to nsINavHistoryService in Gecko 22.0 so that all markPageAs* methods can be found in one interface.

Attributes

Attribute Type Description
count Obsolete since Gecko 15.0 PRUint32 Indicates if there are entries in global history. For performance reasons this does not return the real number of entries. Read only.
lastPageVisited Obsolete since Gecko 10.0 AUTF8String The last page that was visited in a top-level window. Read only.
Note: The count attribute was removed in Gecko 15.0 because it was only used to determine if there were any entries at all anyway, so the nsINavHistoryService.hasHistoryEntries attribute is better for this.

Methods

Obsolete since Gecko 15.0 (Firefox 15.0 / Thunderbird 15.0 / SeaMonkey 2.12)

addPageWithDetails()

Note: This method was removed in Gecko 15.0. You should use mozIAsyncHistory.updatePlaces() instead.

This method adds a page to the history with specific time stamp information. It is called by history importing code and is used in the History migration tool.

void addPageWithDetails(
  in nsIURI aURI,
  in wstring aTitle,
  in long long aLastVisited
);
Parameters
aURI
The page that will be added to the history.
aTitle
The title of the page.
aLastVisited
When the page was last visited, in microseconds since the Unix epoch.

Obsolete since Gecko 22.0 (Firefox 22.0 / Thunderbird 22.0 / SeaMonkey 2.19)

markPageAsFollowedLink()

Note: This method was moved to another interface in Gecko 22.0. You should use nsINavHistoryService.markPageAsFollowedLink() instead. This function was originally added in Gecko 2.0 (Firefox 4/Thunderbird 3.3/SeaMonkey 2.1).

Designates the specified URL as coming from a link explicitly followed by the user (for example by clicking on it).

void markPageAsFollowedLink(
  in nsIURI aURI
);
Parameters
aURI
The URL that is to be marked as explicitly followed by the user.

Obsolete since Gecko 22.0 (Firefox 22.0 / Thunderbird 22.0 / SeaMonkey 2.19)

markPageAsTyped()

Note: This method was moved to another interface in Gecko 22.0. You should use nsINavHistoryService.markPageAsTyped() instead.

This method designates the URL as having been explicitly typed in by the user, so it can be used as an autocomplete result. It is called by the URL bar when the user types in a URL. This can be and is called before the page is actually added to history, since the page isn't added until it actually starts loading. The typed flag affects the URL bar autocomplete. This will cause the transition type of the next visit of the URL to be marked as "typed."

void markPageAsTyped(
  in nsIURI aURI
);
Parameters
aURI
The page that is to be marked as typed by the user.

Obsolete since Gecko 9.0 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6)

registerOpenPage()

Mark a page as being currently open.

Note: This method was an alias for mozIPlacesAutoComplete.registerOpenPage(), which still exists and can be used instead.
void registerOpenPage(
  in nsIURI aURI
);
Parameters
aURI
The page that is to be marked as currently open.

removeAllPages()

This method removes all the pages from the global history.

void removeAllPages();
Parameters

None.

Remarks

Visits are removed synchronously, but pages are expired asynchronously, off the main thread.

Note: Removals are handled in a batch. Single removals are not subject to individual notification; instead, nsINavHistoryObserver.onClearHistory() is called on the history observer.

removePage()

This method removes all visits for a page from the history. The page itself is only deleted when it is not bookmarked and when it is not a place: URI. This method is called by the UI when the user deletes a history entry.

Note: If removing fewer than 10 pages, calling this repeatedly is preferable over calling removePages(), since that's about the point at which the overhead of setting up a batch operation doesn't make sense anymore.
void removePage(
  in nsIURI aURI
);
Parameters
aURI
The added page which is to be removed.

Requires Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

removePages()

Removes multiple pages from history using a batch.

Note: If removing fewer than 10 pages, calling removePage() repeatedly is preferable over calling this, since that's about the point at which the overhead of setting up a batch operation doesn't make sense anymore.
void removePages(
  [array, size_is(aLength)] in nsIURI aURIs,
  in unsigned long aLength,
  in boolean aDoBatchNotify /* parameter removed in Gecko 9.0 */
);
Parameters
aURIs
An array of page URIs to be removed from history.
aLength
The number of pages listed in the aURIs array.
aDoBatchNotify Obsolete since Gecko 9.0
If set to true, the BeginUpdateBatch and EndUpdateBatch events are sent; otherwise, no notification of changes to the history is provided.  This parameter was removed in Gecko 9.0.

Requires Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

removePagesByTimeframe()

Removes all pages within the given timeframe, using a batch.

void removePagesByTimeframe(
  in long long aBeginTime,
  in long long aEndTime
);
Parameters
aBeginTime
The time of the first page to remove, in microseconds from epoch.
aEndTime
The time of the last page to remove, in microseconds from epoch.

removePagesFromHost()

This method removes all the pages from the given host. It is called from the UI when the user deletes a group associated with a host or domain. This method lets you delete pages from a specific host, or pages from all hosts in a given domain.

If aEntireDomain is true, it will assume aHost is a domain, and remove all pages from the entire domain.

void removePagesFromHost(
  in AUTF8String aHost,
  in boolean aEntireDomain
);
Parameters
aHost
The name of the host to be removed. An empty value for this parameter means local files and anything else without a hostname. You can also pass in the localized "(local files)" title given to you by a history query to remove all history information for local files.
aEntireDomain
If set to true, it will assume aHost is a domain, and remove all pages from the entire domain, including subdomains. Set to false otherwise.

Requires Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)

removeVisitsByTimeframe()

Removes all visits within the given timeframe, using a batch. Any pages that become unvisited as a result are also deleted.

void removeVisitsByTimeframe(
  in long long aBeginTime,
  in long long aEndTime
);
Parameters
aBeginTime
The time of the first page to remove, in microseconds from epoch.
aEndTime
The time of the last page to remove, in microseconds from epoch.

Obsolete since Gecko 9.0 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6)

unregisterOpenPage()

Mark a page as no longer being open (either by closing the window or tab, or by navigating away from that page).

Note: This method was an alias for mozIPlacesAutoComplete.unregisterOpenPage(), which still exists and can be used instead.
void unregisterOpenPage(
  in nsIURI aURI
);
Parameters
aURI
The page to unregister as an open page.

See also

Document Tags and Contributors

Contributors to this page: Editmonkey, Sheppy, woby, trevorh, kscarfone, sdwilsh, Swiney, V thunder, Arehman4, One
Last updated by: Sheppy,