toolkit/components/places/mozIAsyncFavicons.idl@129ffea94266 (annotated)
toolkit/components/places/mozIAsyncFavicons.idl
Sat, 03 Jan 2015 20:18:00 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Sat, 03 Jan 2015 20:18:00 +0100
- branch
- TOR_BUG_3246
- changeset 7
- 129ffea94266
- permissions
- -rw-r--r--
Conditionally enable double key logic according to:
private browsing mode or privacy.thirdparty.isolate preference and
implement in GetCookieStringCommon and FindCookie where it counts...
With some reservations of how to convince FindCookie users to test
condition and pass a nullptr when disabling double key logic.
| michael@0 | 1 | /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ |
| michael@0 | 2 | /* This Source Code Form is subject to the terms of the Mozilla Public |
| michael@0 | 3 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
| michael@0 | 4 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
| michael@0 | 5 | |
| michael@0 | 6 | #include "nsISupports.idl" |
| michael@0 | 7 | |
| michael@0 | 8 | interface nsIURI; |
| michael@0 | 9 | interface nsIFaviconDataCallback; |
| michael@0 | 10 | |
| michael@0 | 11 | [scriptable, uuid(8849feef-0ead-4e9b-b63b-8d862c42a736)] |
| michael@0 | 12 | interface mozIAsyncFavicons : nsISupports |
| michael@0 | 13 | { |
| michael@0 | 14 | /** |
| michael@0 | 15 | * Declares that a given page uses a favicon with the given URI and |
| michael@0 | 16 | * attempts to fetch and save the icon data by loading the favicon URI |
| michael@0 | 17 | * through an async network request. |
| michael@0 | 18 | * |
| michael@0 | 19 | * If the icon data already exists, we won't try to reload the icon unless |
| michael@0 | 20 | * aForceReload is true. Similarly, if the icon is in the failed favicon |
| michael@0 | 21 | * cache we won't do anything unless aForceReload is true, in which case |
| michael@0 | 22 | * we'll try to reload the favicon. |
| michael@0 | 23 | * |
| michael@0 | 24 | * This function will only save favicons for pages that are already stored in |
| michael@0 | 25 | * the database, like visited pages or bookmarks. For any other URIs, it |
| michael@0 | 26 | * will succeed but do nothing. This function will also ignore the error |
| michael@0 | 27 | * page favicon URI (see FAVICON_ERRORPAGE_URL below). |
| michael@0 | 28 | * |
| michael@0 | 29 | * Icons that fail to load will automatically be added to the failed favicon |
| michael@0 | 30 | * cache, and this function will not save favicons for non-bookmarked URIs |
| michael@0 | 31 | * when history is disabled. |
| michael@0 | 32 | * |
| michael@0 | 33 | * @note This function is identical to |
| michael@0 | 34 | * nsIFaviconService::setAndLoadFaviconForPage. |
| michael@0 | 35 | * |
| michael@0 | 36 | * @param aPageURI |
| michael@0 | 37 | * URI of the page whose favicon is being set. |
| michael@0 | 38 | * @param aFaviconURI |
| michael@0 | 39 | * URI of the favicon to associate with the page. |
| michael@0 | 40 | * @param aForceReload |
| michael@0 | 41 | * If aForceReload is false, we try to reload the favicon only if we |
| michael@0 | 42 | * don't have it or it has expired from the cache. Setting |
| michael@0 | 43 | * aForceReload to true causes us to reload the favicon even if we |
| michael@0 | 44 | * have a usable copy. |
| michael@0 | 45 | * @param aFaviconLoadType |
| michael@0 | 46 | * Set to FAVICON_LOAD_PRIVATE if the favicon is loaded from a private |
| michael@0 | 47 | * browsing window. Set to FAVICON_LOAD_NON_PRIVATE otherwise. |
| michael@0 | 48 | * @param aCallback |
| michael@0 | 49 | * Once we're done setting and/or fetching the favicon, we invoke this |
| michael@0 | 50 | * callback. |
| michael@0 | 51 | * |
| michael@0 | 52 | * @see nsIFaviconDataCallback in nsIFaviconService.idl. |
| michael@0 | 53 | */ |
| michael@0 | 54 | void setAndFetchFaviconForPage(in nsIURI aPageURI, |
| michael@0 | 55 | in nsIURI aFaviconURI, |
| michael@0 | 56 | in boolean aForceReload, |
| michael@0 | 57 | in unsigned long aFaviconLoadType, |
| michael@0 | 58 | [optional] in nsIFaviconDataCallback aCallback); |
| michael@0 | 59 | |
| michael@0 | 60 | /** |
| michael@0 | 61 | * Sets the data for a given favicon URI either by replacing existing data in |
| michael@0 | 62 | * the database or taking the place of otherwise fetched icon data when |
| michael@0 | 63 | * calling setAndFetchFaviconForPage later. |
| michael@0 | 64 | * |
| michael@0 | 65 | * Favicon data for favicon URIs that are not associated with a page URI via |
| michael@0 | 66 | * setAndFetchFaviconForPage will be stored in memory, but may be expired at |
| michael@0 | 67 | * any time, so you should make an effort to associate favicon URIs with page |
| michael@0 | 68 | * URIs as soon as possible. |
| michael@0 | 69 | * |
| michael@0 | 70 | * It's better to not use this function for chrome: icon URIs since you can |
| michael@0 | 71 | * reference the chrome image yourself. getFaviconLinkForIcon/Page will ignore |
| michael@0 | 72 | * any associated data if the favicon URI is "chrome:" and just return the |
| michael@0 | 73 | * same chrome URI. |
| michael@0 | 74 | * |
| michael@0 | 75 | * This function does NOT send out notifications that the data has changed. |
| michael@0 | 76 | * Pages using this favicons that are visible in history or bookmarks views |
| michael@0 | 77 | * will keep the old icon until they have been refreshed by other means. |
| michael@0 | 78 | * |
| michael@0 | 79 | * This function tries to optimize the favicon size, if it is bigger |
| michael@0 | 80 | * than a defined limit we will try to convert it to a 16x16 png image. |
| michael@0 | 81 | * If the conversion fails and favicon is still bigger than our max accepted |
| michael@0 | 82 | * size it won't be saved. |
| michael@0 | 83 | * |
| michael@0 | 84 | * @param aFaviconURI |
| michael@0 | 85 | * URI of the favicon whose data is being set. |
| michael@0 | 86 | * @param aData |
| michael@0 | 87 | * Binary contents of the favicon to save |
| michael@0 | 88 | * @param aDataLength |
| michael@0 | 89 | * Length of binary data |
| michael@0 | 90 | * @param aMimeType |
| michael@0 | 91 | * MIME type of the data to store. This is important so that we know |
| michael@0 | 92 | * what to report when the favicon is used. You should always set this |
| michael@0 | 93 | * param unless you are clearing an icon. |
| michael@0 | 94 | * @param aExpiration |
| michael@0 | 95 | * Time in microseconds since the epoch when this favicon expires. |
| michael@0 | 96 | * Until this time, we won't try to load it again. |
| michael@0 | 97 | * @throws NS_ERROR_FAILURE |
| michael@0 | 98 | * Thrown if the favicon is overbloated and won't be saved to the db. |
| michael@0 | 99 | */ |
| michael@0 | 100 | void replaceFaviconData(in nsIURI aFaviconURI, |
| michael@0 | 101 | [const,array,size_is(aDataLen)] in octet aData, |
| michael@0 | 102 | in unsigned long aDataLen, |
| michael@0 | 103 | in AUTF8String aMimeType, |
| michael@0 | 104 | [optional] in PRTime aExpiration); |
| michael@0 | 105 | |
| michael@0 | 106 | /** |
| michael@0 | 107 | * Same as replaceFaviconData but the data is provided by a string |
| michael@0 | 108 | * containing a data URL. |
| michael@0 | 109 | * |
| michael@0 | 110 | * @see replaceFaviconData |
| michael@0 | 111 | * |
| michael@0 | 112 | * @param aFaviconURI |
| michael@0 | 113 | * URI of the favicon whose data is being set. |
| michael@0 | 114 | * @param aDataURL |
| michael@0 | 115 | * string containing a data URL that represents the contents of |
| michael@0 | 116 | * the favicon to save |
| michael@0 | 117 | * @param aExpiration |
| michael@0 | 118 | * Time in microseconds since the epoch when this favicon expires. |
| michael@0 | 119 | * Until this time, we won't try to load it again. |
| michael@0 | 120 | * @throws NS_ERROR_FAILURE |
| michael@0 | 121 | * Thrown if the favicon is overbloated and won't be saved to the db. |
| michael@0 | 122 | */ |
| michael@0 | 123 | void replaceFaviconDataFromDataURL(in nsIURI aFaviconURI, |
| michael@0 | 124 | in AString aDataURL, |
| michael@0 | 125 | [optional] in PRTime aExpiration); |
| michael@0 | 126 | |
| michael@0 | 127 | /** |
| michael@0 | 128 | * Retrieves the favicon URI associated to the given page, if any. |
| michael@0 | 129 | * |
| michael@0 | 130 | * @param aPageURI |
| michael@0 | 131 | * URI of the page whose favicon URI we're looking up. |
| michael@0 | 132 | * @param aCallback |
| michael@0 | 133 | * This callback is always invoked to notify the result of the lookup. |
| michael@0 | 134 | * The aURI parameter will be the favicon URI, or null when no favicon |
| michael@0 | 135 | * is associated with the page or an error occurred while fetching it. |
| michael@0 | 136 | * |
| michael@0 | 137 | * @note When the callback is invoked, aDataLen will be always 0, aData will |
| michael@0 | 138 | * be an empty array, and aMimeType will be an empty string, regardless |
| michael@0 | 139 | * of whether a favicon is associated with the page. |
| michael@0 | 140 | * |
| michael@0 | 141 | * @see nsIFaviconDataCallback in nsIFaviconService.idl. |
| michael@0 | 142 | */ |
| michael@0 | 143 | void getFaviconURLForPage(in nsIURI aPageURI, |
| michael@0 | 144 | in nsIFaviconDataCallback aCallback); |
| michael@0 | 145 | |
| michael@0 | 146 | /** |
| michael@0 | 147 | * Retrieves the favicon URI and data associated to the given page, if any. |
| michael@0 | 148 | * |
| michael@0 | 149 | * @param aPageURI |
| michael@0 | 150 | * URI of the page whose favicon URI and data we're looking up. |
| michael@0 | 151 | * @param aCallback |
| michael@0 | 152 | * This callback is always invoked to notify the result of the lookup. The aURI |
| michael@0 | 153 | * parameter will be the favicon URI, or null when no favicon is |
| michael@0 | 154 | * associated with the page or an error occurred while fetching it. If |
| michael@0 | 155 | * aURI is not null, the other parameters may contain the favicon data. |
| michael@0 | 156 | * However, if no favicon data is currently associated with the favicon |
| michael@0 | 157 | * URI, aDataLen will be 0, aData will be an empty array, and aMimeType |
| michael@0 | 158 | * will be an empty string. |
| michael@0 | 159 | * |
| michael@0 | 160 | * @see nsIFaviconDataCallback in nsIFaviconService.idl. |
| michael@0 | 161 | */ |
| michael@0 | 162 | void getFaviconDataForPage(in nsIURI aPageURI, |
| michael@0 | 163 | in nsIFaviconDataCallback aCallback); |
| michael@0 | 164 | }; |
