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
|
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* 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;
[scriptable, uuid(5769F08D-0303-4E38-8FE6-86B5473022F6)]
interface nsIJumpListBuilder : nsISupports
{
/**
* Note: This method is deprecated in favour of obtainAndCacheFaviconAsync,
* which does not use main-thread IO.
*
* Returns the local filesystem path for a favicon for a page hosted at
* faviconURL if we happen to have written one to disk before. If we have not,
* then a background thread retrieves the favicon and will write it to disk
* and NS_ERROR_NOT_AVAILABLE will be thrown.
*
* @param {nsIURI} faviconURL
* The URL for the web page for which we would like a filesystem path for
* the favicon.
* @returns {AString}
* The local filesystem path for the favicon if it has been cached before.
* If it has not been cached before, this method will throw
* NS_ERROR_NOT_AVAILABLE.
* @throws NS_ERROR_NOT_AVAILABLE
* In the event that the favicon has never been cached to disk before.
*/
AString obtainAndCacheFavicon(in nsIURI faviconURL);
/**
* Returns a Promise that resolves with a string representation of a local
* file system path for a favicon cache for a page hosted at faviconURL. If
* no such cache exists, it will be created before returning the path.
* Similarly, if the cache has expired, it will be recreated before returning
* the path.
*
* If the favicon does not match a known favicon within the nsIFaviconService,
* the Promise will reject with an NS_ERROR_FAILURE.
*
* @param {nsIURI} faviconURL
* The URL for the web page for which we would like a filesystem path for
* the favicon.
* @returns {Promise<string, nsresult>}
*/
[implicit_jscontext]
Promise obtainAndCacheFaviconAsync(in nsIURI faviconURL);
/**
* Returns a Promise that resolves with whether or not the Jump List backend
* on the background thread is up and running.
*
* @returns {Promise<boolean>}
* Resolves to true if the backend is ready to accept
* WindowsJumpListShortcutDescriptions. False, otherwise.
* @throws NS_ERROR_FAILURE
* If an attempt to communicate with the background thread fails.
*/
[implicit_jscontext]
Promise isAvailable();
/**
* Asks the Windows Jump List API for any items that might have been removed
* by the user from the Jump List UI.
*
* Important: This should be called prior to any attempt to call
* `populateJumpList` to ensure that any passed in
* WindowsJumpListShortcutDescriptions do not describe items that the user has
* just removed. Failing to do so will cause the Promise returned from
* `populateJumpList` to reject. This is a constraint of the underlying win32
* API. Please see
* https://learn.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-icustomdestinationlist-beginlist
* for more details.
*
* @returns {Promise<string[], nsresult>}
* On success, will return an array of strings for URLs of history that
* have been removed by the user via the Windows Jump List. These items will
* also have had their cached favicons removed from the disk off of the
* main thread. On failure, this will reject with the nsresult failure code.
* @throws NS_ERROR_FAILURE
* If an attempt to communicate with the background thread fails.
*/
[implicit_jscontext]
Promise checkForRemovals();
/**
* Writes a new set of items to the Windows Jump List. This occurs
* asynchronously, off of the main thread.
*
* Important: Callers should first call `checkForRemovals` to remove any
* browsing history items that the user chose to remove in the Jump List
* Only then should any WindowsJumpListShortcutDescriptions be created
* and passed to this method. Any attempt to add
* WindowsJumpListShortcutDescriptions matching items that have been removed
* by the user will result in the returned Promise rejecting. This is a
* constraint of the underlying win32 API. Please see
* https://learn.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-icustomdestinationlist-beginlist
* for more details.
*
* @param {WindowsJumpListShortcutDescription[]} aTaskDescriptions
* 0 or more WindowsJumpListShortcutDescriptions to place items within the
* "tasks" section of the Jump List.
* @param {AString} aCustomTitle
* An optional title for a custom sub-list within the Jump List that will be
* populated via aCustomDescriptions. This must be supplied if
* aCustomDescriptions is not empty.
* @param {WindowsJumpListShortcutDescription[]} aCustomDescriptions
* 0 or more WindowsJumpListShortcutDescriptions to place items within the
* custom section of the Jump List. aCustomTitle must be supplied if this
* array is non-empty.
* @returns {Promise<undefined, nsresult>}
* Returns a Promise that resolves if the Jump List was properly written
* to, and rejects otherwise with the nsresult of the failure.
* @throws NS_ERROR_INVALID_ARG
* If any of the passed arguments do not meet the requirements set out
* above.
* @throws NS_ERROR_FAILURE
* If an attempt to communicate with the background thread fails.
*/
[implicit_jscontext]
Promise populateJumpList(
in jsval aTaskDescriptions,
in AString aCustomTitle,
in jsval aCustomDescriptions
);
/**
* Removes all items from the Jump List.
*
* @returns {Promise<undefined, nsresult>}
* Resolves with undefined on successfully clearing the Jump List. If it
* fails to do so, it will reject with the failure code.
* @throws NS_ERROR_FAILURE
* If an attempt to communicate with the background thread fails.
*/
[implicit_jscontext]
Promise clearJumpList();
};
|
