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
|
/* -*- 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
{
/**
* 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 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();
};
|
