Creating the favicon service
The favicon service's contract ID is
@mozilla.org/browser/favicon-service;1, so to gain access to the favicon service, you should do something like this:
var faviconService = Components.classes["@mozilla.org/browser/favicon-service;1"] .getService(Components.interfaces.nsIFaviconService);
The favicon service stores an expiration time for each favicon. This time is used by
nsIFaviconService.setAndLoadFaviconForPage() to determine if the data is fresh or needs reloading from the server. If you are manually loading favicon data, you can specify the expiration time yourself. Otherwise,
nsIFaviconService.setAndLoadFaviconForPage() will use the default expiration time.
Currently, the default expiration time is set to one day in the future. This makes sure that we aren't obsessively reloading favicons into the database for every page viewed, but also that changes in the favicon will be picked up quickly. Most of the time, the favicon will be served from the browser's cache and will have minimal performance impact.
This expiration time is not the time that the favicon will be deleted. Expiration is handled by
browser/components/places/src/nsNavHistoryExpire.cpp as described in Places Design. The expiration time is only used to determine whether data should be reloaded from the network (or cache) or whether the version in the database is fresh enough.
Getting favicon images
You can use favicons in the browser UI using special annotation URIs.
nsIFaviconService.getFaviconImageForPage() returns an annotation URI for the favicon for a given page, and
nsIFaviconService.getFaviconLinkForIcon() returns an annotation URI for the given favicon. The annotation service's "moz-anno:" protocol handler notices annotations called "favicon" and forwards these to the favicon service. These annotation URIs are described in more detail in Using the Places annotation service.
You should always use
nsIFaviconService.getFaviconImageForPage() to get the favicon for a page. If the page has no favicon, or we have never heard of the page, this function will return a "chrome:" URI of the default favicon. This allows efficient caching, since the default favicon will probably be cached in its decoded form by the image library. If there is an error loading the favicon for an annotation URI, the default favicon data will be returned by the annotation service's protocol handler. However, since the URI will be different from the default favicon, the decoded image will not be cached by the image library.