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    * Note: This method is deprecated in favour of obtainAndCacheFaviconAsync,
  14    * which does not use main-thread IO.
  15    *
  16    * Returns the local filesystem path for a favicon for a page hosted at
  17    * faviconURL if we happen to have written one to disk before. If we have not,
  18    * then a background thread retrieves the favicon and will write it to disk
  19    * and NS_ERROR_NOT_AVAILABLE will be thrown.
  20    *
  21    * @param {nsIURI} faviconURL
  22    *   The URL for the web page for which we would like a filesystem path for
  23    *   the favicon.
  24    * @returns {AString}
  25    *   The local filesystem path for the favicon if it has been cached before.
  26    *   If it has not been cached before, this method will throw
  27    *   NS_ERROR_NOT_AVAILABLE.
  28    * @throws NS_ERROR_NOT_AVAILABLE
  29    *   In the event that the favicon has never been cached to disk before.
  30    */
  31   AString obtainAndCacheFavicon(in nsIURI faviconURL);
  32
  33   /**
  34    * Returns a Promise that resolves with a string representation of a local
  35    * file system path for a favicon cache for a page hosted at faviconURL. If
  36    * no such cache exists, it will be created before returning the path.
  37    * Similarly, if the cache has expired, it will be recreated before returning
  38    * the path.
  39    *
  40    * If the favicon does not match a known favicon within the nsIFaviconService,
  41    * the Promise will reject with an NS_ERROR_FAILURE.
  42    *
  43    * @param {nsIURI} faviconURL
  44    *   The URL for the web page for which we would like a filesystem path for
  45    *   the favicon.
  46    * @returns {Promise<string, nsresult>}
  47    */
  48   [implicit_jscontext]
  49   Promise obtainAndCacheFaviconAsync(in nsIURI faviconURL);
  50
  51   /**
  52    * Returns a Promise that resolves with whether or not the Jump List backend
  53    * on the background thread is up and running.
  54    *
  55    * @returns {Promise<boolean>}
  56    *   Resolves to true if the backend is ready to accept
  57    *   WindowsJumpListShortcutDescriptions. False, otherwise.
  58    * @throws NS_ERROR_FAILURE
  59    *   If an attempt to communicate with the background thread fails.
  60    */
  61   [implicit_jscontext]
  62   Promise isAvailable();
  63
  64   /**
  65    * Asks the Windows Jump List API for any items that might have been removed
  66    * by the user from the Jump List UI.
  67    *
  68    * Important: This should be called prior to any attempt to call
  69    * `populateJumpList` to ensure that any passed in
  70    * WindowsJumpListShortcutDescriptions do not describe items that the user has
  71    * just removed. Failing to do so will cause the Promise returned from
  72    * `populateJumpList` to reject. This is a constraint of the underlying win32
  73    * API. Please see
  74    * https://learn.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-icustomdestinationlist-beginlist
  75    * for more details.
  76    *
  77    * @returns {Promise<string[], nsresult>}
  78    *   On success, will return an array of strings for URLs of history that
  79    *   have been removed by the user via the Windows Jump List. These items will
  80    *   also have had their cached favicons removed from the disk off of the
  81    *   main thread. On failure, this will reject with the nsresult failure code.
  82    * @throws NS_ERROR_FAILURE
  83    *   If an attempt to communicate with the background thread fails.
  84    */
  85   [implicit_jscontext]
  86   Promise checkForRemovals();
  87
  88   /**
  89    * Writes a new set of items to the Windows Jump List. This occurs
  90    * asynchronously, off of the main thread.
  91    *
  92    * Important: Callers should first call `checkForRemovals` to remove any
  93    * browsing history items that the user chose to remove in the Jump List
  94    *  Only then should any WindowsJumpListShortcutDescriptions be created
  95    * and passed to this method. Any attempt to add
  96    * WindowsJumpListShortcutDescriptions matching items that have been removed
  97    * by the user will result in the returned Promise rejecting. This is a
  98    * constraint of the underlying win32 API. Please see
  99    * https://learn.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-icustomdestinationlist-beginlist
 100    * for more details.
 101    *
 102    * @param {WindowsJumpListShortcutDescription[]} aTaskDescriptions
 103    *   0 or more WindowsJumpListShortcutDescriptions to place items within the
 104    *   "tasks" section of the Jump List.
 105    * @param {AString} aCustomTitle
 106    *   An optional title for a custom sub-list within the Jump List that will be
 107    *   populated via aCustomDescriptions. This must be supplied if
 108    *   aCustomDescriptions is not empty.
 109    * @param {WindowsJumpListShortcutDescription[]} aCustomDescriptions
 110    *   0 or more WindowsJumpListShortcutDescriptions to place items within the
 111    *   custom section of the Jump List. aCustomTitle must be supplied if this
 112    *   array is non-empty.
 113    * @returns {Promise<undefined, nsresult>}
 114    *   Returns a Promise that resolves if the Jump List was properly written
 115    *   to, and rejects otherwise with the nsresult of the failure.
 116    * @throws NS_ERROR_INVALID_ARG
 117    *   If any of the passed arguments do not meet the requirements set out
 118    *   above.
 119    * @throws NS_ERROR_FAILURE
 120    *   If an attempt to communicate with the background thread fails.
 121    */
 122   [implicit_jscontext]
 123   Promise populateJumpList(
 124     in jsval aTaskDescriptions,
 125     in AString aCustomTitle,
 126     in jsval aCustomDescriptions
 127   );
 128
 129   /**
 130    * Removes all items from the Jump List.
 131    *
 132    * @returns {Promise<undefined, nsresult>}
 133    *   Resolves with undefined on successfully clearing the Jump List. If it
 134    *   fails to do so, it will reject with the failure code.
 135    * @throws NS_ERROR_FAILURE
 136    *   If an attempt to communicate with the background thread fails.
 137    */
 138   [implicit_jscontext]
 139   Promise clearJumpList();
 140 };