widget/nsIJumpListBuilder.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7 interface nsIURI;
   8
   9 [scriptable, uuid(5769F08D-0303-4E38-8FE6-86B5473022F6)]
  10 interface nsIJumpListBuilder : nsISupports
  11 {
  12   /**
  13    * Returns the local filesystem path for a favicon for a page hosted at
  14    * faviconURL if we happen to have written one to disk before. If we have not,
  15    * then a background thread retrieves the favicon and will write it to disk
  16    * and NS_ERROR_NOT_AVAILABLE will be thrown.
  17    *
  18    * @param {nsIURI} faviconURL
  19    *   The URL for the web page for which we would like a filesystem path for
  20    *   the favicon.
  21    * @returns {AString}
  22    *   The local filesystem path for the favicon if it has been cached before.
  23    *   If it has not been cached before, this method will throw
  24    *   NS_ERROR_NOT_AVAILABLE.
  25    * @throws NS_ERROR_NOT_AVAILABLE
  26    *   In the event that the favicon has never been cached to disk before.
  27    */
  28   AString obtainAndCacheFavicon(in nsIURI faviconURL);
  29
  30   /**
  31    * Returns a Promise that resolves with whether or not the Jump List backend
  32    * on the background thread is up and running.
  33    *
  34    * @returns {Promise<boolean>}
  35    *   Resolves to true if the backend is ready to accept
  36    *   WindowsJumpListShortcutDescriptions. False, otherwise.
  37    * @throws NS_ERROR_FAILURE
  38    *   If an attempt to communicate with the background thread fails.
  39    */
  40   [implicit_jscontext]
  41   Promise isAvailable();
  42
  43   /**
  44    * Asks the Windows Jump List API for any items that might have been removed
  45    * by the user from the Jump List UI.
  46    *
  47    * Important: This should be called prior to any attempt to call
  48    * `populateJumpList` to ensure that any passed in
  49    * WindowsJumpListShortcutDescriptions do not describe items that the user has
  50    * just removed. Failing to do so will cause the Promise returned from
  51    * `populateJumpList` to reject. This is a constraint of the underlying win32
  52    * API. Please see
  53    * https://learn.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-icustomdestinationlist-beginlist
  54    * for more details.
  55    *
  56    * @returns {Promise<string[], nsresult>}
  57    *   On success, will return an array of strings for URLs of history that
  58    *   have been removed by the user via the Windows Jump List. These items will
  59    *   also have had their cached favicons removed from the disk off of the
  60    *   main thread. On failure, this will reject with the nsresult failure code.
  61    * @throws NS_ERROR_FAILURE
  62    *   If an attempt to communicate with the background thread fails.
  63    */
  64   [implicit_jscontext]
  65   Promise checkForRemovals();
  66
  67   /**
  68    * Writes a new set of items to the Windows Jump List. This occurs
  69    * asynchronously, off of the main thread.
  70    *
  71    * Important: Callers should first call `checkForRemovals` to remove any
  72    * browsing history items that the user chose to remove in the Jump List
  73    *  Only then should any WindowsJumpListShortcutDescriptions be created
  74    * and passed to this method. Any attempt to add
  75    * WindowsJumpListShortcutDescriptions matching items that have been removed
  76    * by the user will result in the returned Promise rejecting. This is a
  77    * constraint of the underlying win32 API. Please see
  78    * https://learn.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-icustomdestinationlist-beginlist
  79    * for more details.
  80    *
  81    * @param {WindowsJumpListShortcutDescription[]} aTaskDescriptions
  82    *   0 or more WindowsJumpListShortcutDescriptions to place items within the
  83    *   "tasks" section of the Jump List.
  84    * @param {AString} aCustomTitle
  85    *   An optional title for a custom sub-list within the Jump List that will be
  86    *   populated via aCustomDescriptions. This must be supplied if
  87    *   aCustomDescriptions is not empty.
  88    * @param {WindowsJumpListShortcutDescription[]} aCustomDescriptions
  89    *   0 or more WindowsJumpListShortcutDescriptions to place items within the
  90    *   custom section of the Jump List. aCustomTitle must be supplied if this
  91    *   array is non-empty.
  92    * @returns {Promise<undefined, nsresult>}
  93    *   Returns a Promise that resolves if the Jump List was properly written
  94    *   to, and rejects otherwise with the nsresult of the failure.
  95    * @throws NS_ERROR_INVALID_ARG
  96    *   If any of the passed arguments do not meet the requirements set out
  97    *   above.
  98    * @throws NS_ERROR_FAILURE
  99    *   If an attempt to communicate with the background thread fails.
 100    */
 101   [implicit_jscontext]
 102   Promise populateJumpList(
 103     in Array<jsval> aTaskDescriptions,
 104     in AString aCustomTitle,
 105     in Array<jsval> aCustomDescriptions
 106   );
 107
 108   /**
 109    * Removes all items from the Jump List.
 110    *
 111    * @returns {Promise<undefined, nsresult>}
 112    *   Resolves with undefined on successfully clearing the Jump List. If it
 113    *   fails to do so, it will reject with the failure code.
 114    * @throws NS_ERROR_FAILURE
 115    *   If an attempt to communicate with the background thread fails.
 116    */
 117   [implicit_jscontext]
 118   Promise clearJumpList();
 119 };