1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#include "nsISupports.idl"
interface nsIURI;
interface nsIPrincipal;
[scriptable, uuid(e81e0b0c-b9f1-4c2e-8f3c-b809933cf73c)]
interface nsIFaviconService : nsISupports
{
// The favicon is being loaded from a private browsing window
const unsigned long FAVICON_LOAD_PRIVATE = 1;
// The favicon is being loaded from a non-private browsing window
const unsigned long FAVICON_LOAD_NON_PRIVATE = 2;
// Defines values for icon flags.
const unsigned short ICONDATA_FLAGS_RICH = 1 << 0;
/**
* The limit in bytes of the size of favicons in memory and passed via the
* favicon protocol.
*/
const unsigned long MAX_FAVICON_BUFFER_SIZE = 65536;
/**
* 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 URIs, this will do
* nothing but returning 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
* cached-favicon protocol handler's special case for cached favicon will
* resolve invalid icons to the default icon, although without caching.
* For invalid chrome URIs, you'll get a broken image.
*
* @param aFaviconURI
* The URI of an icon in the favicon service.
* @return 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 async from
* this service. For pages where we don't have a favicon, this will
* be a chrome URI of the default icon. For chrome URIs, the
* output will be the same as the input.
*/
nsIURI getFaviconLinkForIcon(in nsIURI aFaviconURI);
/**
* Expire all known favicons from the database.
*
* @note This is an async method.
* On successful completion a "places-favicons-expired" notification is
* dispatched through observer's service.
*/
void expireAllFavicons();
/**
* Sets the default size returned by preferredSizeFromURI when the uri doesn't
* specify a size ref. If this is not invoked first, or 0 is passed to it,
* preferredSizeFromURI() will return UINT16_MAX, that matches the biggest
* icon available.
*/
void setDefaultIconURIPreferredSize(in unsigned short aDefaultSize);
/**
* Tries to extract the preferred size from an icon uri ref fragment.
*
* @param aURI
* The URI to parse.
* @return The preferred size, or a default size set through
* setDefaultIconURIPreferredSize, or UINT16_MAX if neither are set.
*/
unsigned short preferredSizeFromURI(in nsIURI aURI);
/**
* The default favicon URI
*/
readonly attribute nsIURI defaultFavicon;
/**
* The default favicon mimeType
*/
readonly attribute AUTF8String defaultFaviconMimeType;
/**
* Stores the relation between a page URI and a favicon URI, whose icon data
* is provided through a data URL.
* The process is asynchronous and a callback with the status of the operation
* will be invoked at the end of it.
*
* @param aPageURI
* URI of the page whose favicon is being set.
* @param aFaviconURI
* URI of the favicon to associate with the page.
* @param aDataURL
* String that represents a data URL to replace as the favicon content.
* @param [optional] aExpiration
* Time in microseconds since the epoch when this favicon expires.
* Until this time, we won't try to load it again.
* If this argument is omitted, the expiration defaults to
* 7 days (FaviconHelpers::MAX_FAVICON_EXPIRATION) from now.
*
* @return Promise that is resolved/rejected when finishing the process.
*
* @throws NS_ERROR_FILE_TOO_BIG if the icon is excessively large and can not
* be optimized internally.
*/
[implicit_jscontext, must_use]
Promise setFaviconForPage(
in nsIURI aPageURI,
in nsIURI aFaviconURI,
in nsIURI aDataURL,
[optional] in PRTime aExpiration,
[optional] in boolean isRichIcon
);
/**
* Retrieves the favicon URI and data URL associated to the given page, if any.
* If the page icon is not available, it will try to return the root domain
* icon data, when it's known.
*
* @param aPageURI
* URI of the page whose favicon URI and data we're looking up.
* @param [optional] aPreferredWidth
* The preferred icon width, skip or pass 0 for the default value,
* set through setDefaultIconURIPreferredSize.
*
* @return Promise that is resolved/rejected when finishing the process.
* If succeeded, the promise resolved with nsIFavicon. If there is no
* data in the database, this promise resolved with null. On the other
* hand, rejected if the DB access fails, for example.
*/
[implicit_jscontext, must_use]
Promise getFaviconForPage(in nsIURI aPageURI, [optional]
in unsigned short aPreferredWidth);
/**
* Try to copy cached favicons from a page to another one.
*
* @param aFromPageURI
* URI of the originating page.
* @param aToPageURI
* URI of the destination page.
* @param aFaviconLoadType
* Set to FAVICON_LOAD_PRIVATE if the copy is started from a private
* browsing window. Set to FAVICON_LOAD_NON_PRIVATE otherwise.
* @return Promise that is resolved/rejected when finishing the process.
* If succeeded to copy, the promise resolved with true. Otherwise
* false. Will reject if the paramter value is illeagal or DB access
* fails etc.
*/
[implicit_jscontext, must_use]
Promise tryCopyFavicons(in nsIURI aFromPageURI,
in nsIURI aToPageURI,
in unsigned long aFaviconLoadType);
};
[scriptable, uuid(c23c74d6-9c36-4223-a9c4-c8b95526f4d3)]
interface nsIFavicon : nsISupports
{
/**
* Favicon location.
*/
readonly attribute nsIURI uri;
/**
* Favicon data as Data URL.
*/
readonly attribute nsIURI dataURI;
/**
* Favicon raw data.
*/
readonly attribute Array<octet> rawData;
/**
* Favicon mime type.
*/
readonly attribute ACString mimeType;
/**
* Favicon width.
*/
readonly attribute unsigned short width;
};
%{C++
/**
* Notification sent when all favicons are expired.
*/
#define NS_PLACES_FAVICONS_EXPIRED_TOPIC_ID "places-favicons-expired"
#define FAVICON_DEFAULT_URL "chrome://global/skin/icons/defaultFavicon.svg"
#define FAVICON_DEFAULT_MIMETYPE "image/svg+xml"
#define FAVICON_ERRORPAGE_URL "chrome://global/skin/icons/info.svg"
#define FAVICON_CERTERRORPAGE_URL "chrome://global/skin/icons/warning.svg"
%}
|
