Source code
Revision control
Copy as Markdown
Other Tools
/* -*- 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
#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
* 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
* 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();
};