nsISupports
Last changed in Gecko 22.0 (Firefox 22.0 / Thunderbird 22.0 / SeaMonkey 2.19)Implemented by: @mozilla.org/browser/favicon-service;1
. To use this service, use:
var faviconService = Components.classes["@mozilla.org/browser/favicon-service;1"] .getService(Components.interfaces.nsIFaviconService);
Method overview
void addFailedFavicon(in nsIURI aFaviconURI); |
void expireAllFavicons(); |
void getFaviconData(in nsIURI aFaviconURI, out AUTF8String aMimeType, [optional] out unsigned long aDataLen, [array,retval,size_is(aDataLen)] out octet aData); Obsolete since Gecko 22.0 |
AString getFaviconDataAsDataURL(in nsIURI aFaviconURI); Obsolete since Gecko 22.0 |
nsIURI getFaviconForPage(in nsIURI aPageURI); Obsolete since Gecko 22.0 |
nsIURI getFaviconImageForPage(in nsIURI aPageURI); Obsolete since Gecko 22.0 |
nsIURI getFaviconLinkForIcon(in nsIURI aFaviconURI); |
boolean isFailedFavicon(in nsIURI aFaviconURI); |
void removeFailedFavicon(in nsIURI aFaviconURI); |
void setAndLoadFaviconForPage(in nsIURI aPageURI, in nsIURI aFaviconURI, in boolean aForceReload, in unsigned long aFaviconLoadType, [optional] in nsIFaviconDataCallback aCallback); Obsolete since Gecko 22.0 |
void setFaviconData(in nsIURI aFaviconURI, [const,array,size_is(aDataLen)] in octet aData, in unsigned long aDataLen, in AUTF8String aMimeType, in PRTime aExpiration); Obsolete since Gecko 22.0 |
void setFaviconDataFromDataURL(in nsIURI aFaviconURI, in AString aDataURL, in PRTime aExpiration); Obsolete since Gecko 22.0 |
void setFaviconUrlForPage(in nsIURI aPageURI, in nsIURI aFaviconURI); Obsolete since Gecko 22.0 |
Attributes
Attribute | Type | Description |
defaultFavicon |
|
The default favicon URI. Read only. |
Methods
addFailedFavicon()
This method 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()
method and it encounters an error while fetching an icon.
void addFailedFavicon( in nsIURI aFaviconURI );
Parameters
-
aFaviconURI
-
The URI of an icon in the favicon service. Can be
null
.
expireAllFavicons()
Expires all known favicons, removing them from the database.
void expireAllFavicons();
Parameters
None.
getFaviconData()
Note: This method was removed in Gecko 22.0. You should use the new async API mozIAsyncFavicons.getFaviconDataForPage()
instead.
This method retrieves the given favicon data. Throws an exception if we don't have data.
If there is no data but we have an entry for this favicon, aDataLen
will be "0"
and aData
will be null
.
void getFaviconData(
in nsIURI aFaviconURI,
out AUTF8String aMimeType,
out unsigned long aDataLen, Optional from Gecko 2.0
[array,retval,size_is(aDataLen)] out octet aData
);
Parameters
-
aFaviconURI
- URI of the favicon whose data is being read.
-
aMimeType
-
Output parameter where the
MIME
type will be placed. -
aDataLen
- Output parameter where the size of the binary data will be placed.
-
aData
-
Output parameter where the binary favicon data will be placed. This will be
null
if we have this URI but have no data associated with it.
Exceptions thrown
-
NS_ERROR_NOT_AVAILABLE
- Thrown when we have never heard of this favicon URL.
getFaviconDataAsDataURL()
Note: This method was removed in Gecko 22.0. You should use the new async API mozIAsyncFavicons.getFaviconDataForPage()
instead.
This method retrieves the given favicon data, returning it as a data
URL Throws an exception if we don't have data.
If there is no data but we have an entry for this favicon, returns null
.
AString getFaviconDataAsDataURL( in nsIURI aFaviconURI );
Parameters
-
aFaviconURI
- URI of the favicon whose data is being read.
Return value
A data
URL containing the data for the favicon. This is null
if there is no data but there is an entry for the favicon.
Exceptions thrown
-
NS_ERROR_NOT_AVAILABLE
- Thrown when we have never heard of this favicon URL.
getFaviconForPage()
Note: This method was removed in Gecko 22.0. You should use the new async API mozIAsyncFavicons.getFaviconURLForPage()
instead.
This method retrieves the URI of the favicon for the given page.
nsIURI getFaviconForPage( in nsIURI aPageURI );
Parameters
-
aPageURI
- URI of the page whose favicon is desired.
Return value
Returns the URI of the favicon associated with that page. Returning a URI here does NOT mean that we have data for this favicon, only that we know what the favicon should be.
Exceptions thrown
-
NS_ERROR_NOT_AVAILABLE
- When the page is not found or it has no favicon.
getFaviconImageForPage()
Note: This method was removed in Gecko 22.0. You should use the new async API mozIAsyncFavicons.getFaviconURLForPage()
and getFaviconLinkForIcon()
instead.
This method is very similar to that of getFaviconLinkForIcon()
method. For a given page 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.
When compared to getFaviconLinkForIcon()
method, this method only adds the extra level of indirection, looking up the favicon based on the page URI and using the default if not found.
nsIURI getFaviconImageForPage( in nsIURI aPageURI );
Parameters
-
aPageURI
- URI of the page whose favicon is desired.
Return value
Returns a URI that will give you the icon image. This is not the URI of the icon as set on the page, but a URI that will give you the data out of the favicon service. For a normal page with a favicon we've stored, this will be an annotation URI which will then cause the corresponding favicon data to be loaded from this service. For pages where we don't have a favicon, this will be a chrome URI of the default icon for a web page.
getFaviconLinkForIcon()
This method, for a given icon URI 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.
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 resolve invalid icons to the default icon, although without caching. For invalid chrome URIs, you'll get a broken image.
nsIURI getFaviconLinkForIcon( in nsIURI aFaviconURI );
Parameters
-
aFaviconURI
- The URI of an icon in the favicon service.
Return value
Returns a URI that will load the desired icon. This is not the URI of the icon as set on the page, but a URI that will give you the data out of the favicon service. For a normal page with a favicon we've stored, this will be an annotation URI which will then cause the corresponding favicon data to be loaded from this service. For pages where we don't have a favicon, this will be a chrome URI of the default icon for a web page. For chrome, the output will be the same as the input. For chrome, the output will be the same as the input.
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.
isFailedFavicon()
This method checks to see if this favicon is in the failed favicon cache.
boolean isFailedFavicon( in nsIURI aFaviconURI );
Parameters
-
aFaviconURI
-
The URI of an icon in the favicon service. Can be
null
.
Return value
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.
removeFailedFavicon()
This method removes the given favicon from the failed favicon cache. If the icon is not in the cache, this function will silently succeed.
void removeFailedFavicon( in nsIURI aFaviconURI );
Parameters
-
aFaviconURI
-
The URI of an icon in the favicon service. Can be
null
.
setAndLoadFaviconForPage()
Note: This method was removed in Gecko 22.0. You should use the new async API mozIAsyncFavicons.setAndFetchFaviconForPage()
instead.
This method is 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 aForceReload
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 the error page favicon URI (chrome://global/skin/icons/warning-16.png
). 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.
void setAndLoadFaviconForPage(
in nsIURI aPageURI,
in nsIURI aFaviconURI,
in boolean aForceReload,
in unsigned long aFaviconLoadType,
in nsIFaviconDataCallback aCallback Optional from Gecko 2.0
);
Parameters
-
aPageURI
- URI of the page whose favicon is being set.
-
aFaviconURI
- URI of the favicon to associate with the page.
-
aForceReload
- 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.
-
aFaviconLoadType
-
One of
nsIFaviconService.FAVICON_LOAD_PRIVATE
ornsIFaviconService.FAVICON_LOAD_NON_PRIVATE
to indicate that any network requests performed should act like ones from a private browsing context (ie. no history entries, only store in the temporary disk cache, etc.). This should be determined viaPrivateBrowsingUtils.isWindowPrivate(someRelatedWindow)
if the favicon may expose the user's private browsing data by performing a network request, otherwiseFAVICON_LOAD_NON_PRIVATE
may be used. -
aCallback
Optional from Gecko 2.0 -
An
nsIFaviconDataCallback
.
Example
var ioservice = Components.classes["@mozilla.org/network/io-service;1"] .getService(Components.interfaces.nsIIOService); var pageURI = ioservice.newURI("https://www.mozilla.org/", null, null); var faviconURI = ioservice.newURI("https://www.mozilla.org/favicon.ico", null, null); faviconService.setAndLoadFaviconForPage(pageURI, faviconURI, false);
setFaviconData()
Note: This method was removed in Gecko 22.0. You should use the new async API mozIAsyncFavicons.replaceFaviconData()
instead.
This method 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()
and getFaviconForPage()
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.
void setFaviconData(
in nsIURI aFaviconURI,
[const,array,size_is(aDataLen)] in octet aData,
in unsigned long aDataLen, Optional from Gecko 2.0
in AUTF8String aMimeType,
in PRTime aExpiration
);
Parameters
-
aFaviconURI
- URI of the favicon whose data is being set.
-
aData
- Binary contents of the favicon to save.
-
aDataLen
Optional from Gecko 2.0 - Length of binary data.
-
aMimeType
-
MIME
type of the data to store. This is important so that we know what to report when the favicon is used. You should always set this param unless you are clearing an icon. -
aExpiration
- Time in microseconds since the epoch when this favicon expires. Until this time, we won't try to load it again.
Exceptions thrown
-
NS_ERROR_FAILURE
- Thrown if the favicon is overbloated and won't be saved to the db.
setFaviconDataFromDataURL()
Note: This method was removed in Gecko 22.0. You should use the new async API mozIAsyncFavicons.replaceFaviconDataFromDataURL()
instead.
This method stores the data of a given favicon. The data is provided using a data
URL string.
This function tries to optimize the favicon size; if it's bigger than a defined limit, Gecko attempts to convert it to a 16x16 pixel PNG image. If that fails and the image is bigger than a maximum acceptable favicon size, the entire operation fails and the favicon isn't saved.
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()
and getFaviconForPage()
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.
void setFaviconDataFromDataURL( in nsIURI aFaviconURI, in AString aDataURL, in PRTime aExpiration );
Parameters
-
aFaviconURI
- URI of the favicon whose data is being set.
-
aDataURL
- String containing a data URL that represents the contents of the favicon to save.
-
aExpiration
- The time in microseconds since epoch when this favicon expires; until this time, we won't try to load the favicon again.
Exceptions thrown
-
NS_ERROR_FAILURE
- Thrown if the favicon is overbloated and won't be saved to the db.
setFaviconUrlForPage()
Note: This method was removed in Gecko 22.0. You should use the new async API mozIAsyncFavicons.setAndFetchFaviconForPage()
instead.
This method declares that a given page uses a favicon with the given URI.
You needn't have any specified 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.
void setFaviconUrlForPage( in nsIURI aPageURI, in nsIURI aFaviconURI );
Parameters
-
aPageURI
- URI of the page whose favicon is being set.
-
aFaviconURI
- URI of the favicon to associate with the page.