1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/components/places/mozIAsyncFavicons.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,164 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIURI;
1.12 +interface nsIFaviconDataCallback;
1.13 +
1.14 +[scriptable, uuid(8849feef-0ead-4e9b-b63b-8d862c42a736)]
1.15 +interface mozIAsyncFavicons : nsISupports
1.16 +{
1.17 + /**
1.18 + * Declares that a given page uses a favicon with the given URI and
1.19 + * attempts to fetch and save the icon data by loading the favicon URI
1.20 + * through an async network request.
1.21 + *
1.22 + * If the icon data already exists, we won't try to reload the icon unless
1.23 + * aForceReload is true. Similarly, if the icon is in the failed favicon
1.24 + * cache we won't do anything unless aForceReload is true, in which case
1.25 + * we'll try to reload the favicon.
1.26 + *
1.27 + * This function will only save favicons for pages that are already stored in
1.28 + * the database, like visited pages or bookmarks. For any other URIs, it
1.29 + * will succeed but do nothing. This function will also ignore the error
1.30 + * page favicon URI (see FAVICON_ERRORPAGE_URL below).
1.31 + *
1.32 + * Icons that fail to load will automatically be added to the failed favicon
1.33 + * cache, and this function will not save favicons for non-bookmarked URIs
1.34 + * when history is disabled.
1.35 + *
1.36 + * @note This function is identical to
1.37 + * nsIFaviconService::setAndLoadFaviconForPage.
1.38 + *
1.39 + * @param aPageURI
1.40 + * URI of the page whose favicon is being set.
1.41 + * @param aFaviconURI
1.42 + * URI of the favicon to associate with the page.
1.43 + * @param aForceReload
1.44 + * If aForceReload is false, we try to reload the favicon only if we
1.45 + * don't have it or it has expired from the cache. Setting
1.46 + * aForceReload to true causes us to reload the favicon even if we
1.47 + * have a usable copy.
1.48 + * @param aFaviconLoadType
1.49 + * Set to FAVICON_LOAD_PRIVATE if the favicon is loaded from a private
1.50 + * browsing window. Set to FAVICON_LOAD_NON_PRIVATE otherwise.
1.51 + * @param aCallback
1.52 + * Once we're done setting and/or fetching the favicon, we invoke this
1.53 + * callback.
1.54 + *
1.55 + * @see nsIFaviconDataCallback in nsIFaviconService.idl.
1.56 + */
1.57 + void setAndFetchFaviconForPage(in nsIURI aPageURI,
1.58 + in nsIURI aFaviconURI,
1.59 + in boolean aForceReload,
1.60 + in unsigned long aFaviconLoadType,
1.61 + [optional] in nsIFaviconDataCallback aCallback);
1.62 +
1.63 + /**
1.64 + * Sets the data for a given favicon URI either by replacing existing data in
1.65 + * the database or taking the place of otherwise fetched icon data when
1.66 + * calling setAndFetchFaviconForPage later.
1.67 + *
1.68 + * Favicon data for favicon URIs that are not associated with a page URI via
1.69 + * setAndFetchFaviconForPage will be stored in memory, but may be expired at
1.70 + * any time, so you should make an effort to associate favicon URIs with page
1.71 + * URIs as soon as possible.
1.72 + *
1.73 + * It's better to not use this function for chrome: icon URIs since you can
1.74 + * reference the chrome image yourself. getFaviconLinkForIcon/Page will ignore
1.75 + * any associated data if the favicon URI is "chrome:" and just return the
1.76 + * same chrome URI.
1.77 + *
1.78 + * This function does NOT send out notifications that the data has changed.
1.79 + * Pages using this favicons that are visible in history or bookmarks views
1.80 + * will keep the old icon until they have been refreshed by other means.
1.81 + *
1.82 + * This function tries to optimize the favicon size, if it is bigger
1.83 + * than a defined limit we will try to convert it to a 16x16 png image.
1.84 + * If the conversion fails and favicon is still bigger than our max accepted
1.85 + * size it won't be saved.
1.86 + *
1.87 + * @param aFaviconURI
1.88 + * URI of the favicon whose data is being set.
1.89 + * @param aData
1.90 + * Binary contents of the favicon to save
1.91 + * @param aDataLength
1.92 + * Length of binary data
1.93 + * @param aMimeType
1.94 + * MIME type of the data to store. This is important so that we know
1.95 + * what to report when the favicon is used. You should always set this
1.96 + * param unless you are clearing an icon.
1.97 + * @param aExpiration
1.98 + * Time in microseconds since the epoch when this favicon expires.
1.99 + * Until this time, we won't try to load it again.
1.100 + * @throws NS_ERROR_FAILURE
1.101 + * Thrown if the favicon is overbloated and won't be saved to the db.
1.102 + */
1.103 + void replaceFaviconData(in nsIURI aFaviconURI,
1.104 + [const,array,size_is(aDataLen)] in octet aData,
1.105 + in unsigned long aDataLen,
1.106 + in AUTF8String aMimeType,
1.107 + [optional] in PRTime aExpiration);
1.108 +
1.109 + /**
1.110 + * Same as replaceFaviconData but the data is provided by a string
1.111 + * containing a data URL.
1.112 + *
1.113 + * @see replaceFaviconData
1.114 + *
1.115 + * @param aFaviconURI
1.116 + * URI of the favicon whose data is being set.
1.117 + * @param aDataURL
1.118 + * string containing a data URL that represents the contents of
1.119 + * the favicon to save
1.120 + * @param aExpiration
1.121 + * Time in microseconds since the epoch when this favicon expires.
1.122 + * Until this time, we won't try to load it again.
1.123 + * @throws NS_ERROR_FAILURE
1.124 + * Thrown if the favicon is overbloated and won't be saved to the db.
1.125 + */
1.126 + void replaceFaviconDataFromDataURL(in nsIURI aFaviconURI,
1.127 + in AString aDataURL,
1.128 + [optional] in PRTime aExpiration);
1.129 +
1.130 + /**
1.131 + * Retrieves the favicon URI associated to the given page, if any.
1.132 + *
1.133 + * @param aPageURI
1.134 + * URI of the page whose favicon URI we're looking up.
1.135 + * @param aCallback
1.136 + * This callback is always invoked to notify the result of the lookup.
1.137 + * The aURI parameter will be the favicon URI, or null when no favicon
1.138 + * is associated with the page or an error occurred while fetching it.
1.139 + *
1.140 + * @note When the callback is invoked, aDataLen will be always 0, aData will
1.141 + * be an empty array, and aMimeType will be an empty string, regardless
1.142 + * of whether a favicon is associated with the page.
1.143 + *
1.144 + * @see nsIFaviconDataCallback in nsIFaviconService.idl.
1.145 + */
1.146 + void getFaviconURLForPage(in nsIURI aPageURI,
1.147 + in nsIFaviconDataCallback aCallback);
1.148 +
1.149 + /**
1.150 + * Retrieves the favicon URI and data associated to the given page, if any.
1.151 + *
1.152 + * @param aPageURI
1.153 + * URI of the page whose favicon URI and data we're looking up.
1.154 + * @param aCallback
1.155 + * This callback is always invoked to notify the result of the lookup. The aURI
1.156 + * parameter will be the favicon URI, or null when no favicon is
1.157 + * associated with the page or an error occurred while fetching it. If
1.158 + * aURI is not null, the other parameters may contain the favicon data.
1.159 + * However, if no favicon data is currently associated with the favicon
1.160 + * URI, aDataLen will be 0, aData will be an empty array, and aMimeType
1.161 + * will be an empty string.
1.162 + *
1.163 + * @see nsIFaviconDataCallback in nsIFaviconService.idl.
1.164 + */
1.165 + void getFaviconDataForPage(in nsIURI aPageURI,
1.166 + in nsIFaviconDataCallback aCallback);
1.167 +};
