void addFailedFavicon ( nsIURI icon )

Adds a given favicon's URI to the failed favicon cache.

The lifespan of the favicon cache is up to the caching system. This cache will also be written to if you use setAndLoadFaviconForPage and it encounters an error.

Arguments:

icon

void getFaviconData ( nsIURI favicon , out AUTF8String mimeType , out PRUint32 dataLen , out arrayof PRUint8 data )

Retrieves the given favicon data. Throws if we don't have data.

If there is no data but we have an entry for this favicon, dataLen will be 0 and data will be NULL.

Arguments:

favicon: URL of the favicon whose data is being read

mimeType: Output parameter where the MIME type will be placed.

dataLen: Output parameter where the size of the binary data will be placed.

data: Output parameter where the binary favicon data will be placed. This will be null if we have this URL but have no data associated with it.

nsIURI getFaviconForPage ( nsIURI page )

Retrieves the URL of the favicon for the given page.

Arguments:

page: URI of the page whose favicon is desired

nsIURI getFaviconImageForPage ( nsIURI page )

For a given page, this will give you a URI that, when displayed in chrome, will result in the given page's favicon. Unlike the other get functions, we needn't have heard of the page or its favicon: the default one will be returned in this case.

Arguments:

page: URI of the page whose favicon is desired

nsIURI getFaviconLinkForIcon ( nsIURI icon )

For a given icon URI, this will return a URI that will result in the image. In most cases, this is an annotation URI. For chrome, this will do nothing and return the input URI. For NULL input, this will return the URI of the default favicon.

No validity checking is done. If you pass an icon URI that we've never seen, you'll get back a URI that references an invalid icon. The moz-anno protocol handler's special case for "favicon" annotations will detect most invalid icons and it will resolve to the default icon, although without caching. For invalid chrome URIs, you'll get a broken image.

Arguments:

icon: The URL of an icon in the favicon service. Can be NULL.

PRBool isFailedFavicon ( nsIURI icon )

Checks to see if this favicon is in the failed favicon cache. Returns true if the favicon is in the failed cache, meaning you probably shouldn't try to load it. A false return value means that it's worth trying to load it. This allows you to avoid trying to load "foo.com/favicon.ico" for every page on a site that doesn't have a favicon.

Arguments:

icon

void removeFailedFavicon ( nsIURI icon )

Removes the given favicon from the failed favicon cache. If the icon is not in the cache, this function will silently succeed.

Arguments:

icon

void setAndLoadFaviconForPage ( nsIURI page , nsIURI favicon , PRBool forceReload )

Same as SetFaviconUrlForPage except that this also attempts to set the data by loading the favicon URI. An async request will be created for this URI and if the data is available, it will asynchronously get saved in the database without any further work from the caller.

If the icon data already exists, we won't normally try to re-load the icon from the net (or more likely the cache). If the icon is in the failed favicon cache we won't do anything. Use forceReload to force a reload of the data. This will remove the favicon from the failed cache. If it then fails again, it will be re-added to the failed cache.

SetFaviconUrlForPage and SetFaviconData will take any URL you provide and save it. This function is intended for automatic usage, and will only save favicons for "good" URLs, as defined by what gets added to history. For "bad" URLs, this function will succeed and do nothing. This function will also ignore favicons that are data URLs. Icons that fail to load will automatically be added to the failed favicon cache.

This function will not save favicons for non-bookmarked URLs when history is disabled (expiration time is 0 days). The rest of the functions here will always store favicons even when history is disabled.

Arguments:

page: URI of the page whose favicon is being set.

favicon: URI of the favicon to associate with the page.

forceReload: Unset is normal behavior, we will only try to reload the favicon if we don't have it or if it has expired from the cache. If set, it will always try to reload the favicon.

void setFaviconData ( nsIURI favicon , arrayof PRUint8 data , PRUint32 dataLen , AUTF8String mimeType , PRTime expiration )

Stores the data of a given favicon. You must specify the MIME type unless you're clearing the data.

You can set the data even if you haven't called SetFaviconUrlForPage yet. It will be stored but will not be associated with any page. However, any favicons not associated with a visited web page, bookmark, or "place:" URI will be expired when history cleanup is done. This might be done at any time on a timer, so you should not let the message loop run between calls or your icon may get deleted.

It is best to set the favicon data, and then associate it with a page. This will make the notifications more efficient since the icon will already have data when the set favicon observer messages goes out.

The expiration time is stored. This will be used if you call SetAndLoadFaviconForPage to see whether the data needs reloading.

Do not use this function for chrome: icon URLs. You should reference the chrome image yourself. The GetFaviconLinkForIcon/Page will ignore any associated data if the favicon URI is "chrome:" and just return the same chrome URI.

This function does NOT send out notifications that the data has changed. Potentially, many pages could be referencing the favicon and they could be visible in a history view or toolbar. But sending out those notifications is very intensive. Those pages will keep the old icon until they have been refreshed by other means.

Arguments:

favicon: URI of the favicon whose data is being set.

data: Binary contents of the favicon to save

dataLen

mimeType: MIME type of the data to store. This is important so that we know what to report when the favicon is used.

expiration: Time in microseconds since the epoch when this favicon expires. Until this time, we won't try to load it again.

void setFaviconUrlForPage ( nsIURI page , nsIURI favicon )

Declares that a given page uses a favicon with the given URI.

You needn't have specified any data at this point. An entry linking the favicon with the page will be create with no data. You can populate it later with SetFaviconData. However, any favicons not associated with a visited web page, a bookmark, or a "place:" URI will be expired when history cleanup is done * (typically at app shutdown, but also possibly if the user clears their * cache or history).

This will send out history notifications if the new favicon has any data. This means that you should try to set data first if you have it, otherwise the page might not get a notification sent for it since data setting does not send notifications.

Arguments:

page: URI of the page whose favicon is being set.

favicon: URI of the favicon to associate with the page.