summaryrefslogtreecommitdiffstats
path: root/widget/nsIJumpListBuilder.idl
diff options
context:
space:
mode:
Diffstat (limited to 'widget/nsIJumpListBuilder.idl')
-rw-r--r--widget/nsIJumpListBuilder.idl119
1 files changed, 119 insertions, 0 deletions
diff --git a/widget/nsIJumpListBuilder.idl b/widget/nsIJumpListBuilder.idl
new file mode 100644
index 0000000000..1b7b93e5e7
--- /dev/null
+++ b/widget/nsIJumpListBuilder.idl
@@ -0,0 +1,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 Array<jsval> aTaskDescriptions,
+ in AString aCustomTitle,
+ in Array<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();
+};