browser/components/shell/nsIWindowsShellService.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 interface nsIFile;
   8
   9 [scriptable, uuid(fb9b59db-5a91-4e67-92b6-35e7d6e6d3fd)]
  10 interface nsIWindowsShellService : nsISupports
  11 {
  12   /*
  13    * Creates a new shortcut (.lnk) file. This shortcut will be recorded in
  14    * a new shortcuts log file located in %PROGRAMDATA%\Mozilla-1de4eec8-1241-4177-a864-e594e8d1fb38
  15    * that is named after the currently running application and current user, eg:
  16    * Firefox_user123_shortcuts.ini.
  17    *
  18    * For reasons that we haven't been able to pin down, these shortcuts get created with
  19    * extra metadata on them (KnownFolderDataBlock, SpecialFolderDataBlock) that cause
  20    * the Windows ShellLink classes to improperly read their target path with certain
  21    * parameters. This causes any 32-bit programs that read the links (such as our
  22    * installer and uninstaller) to think that 64-bit installs are located in the 32-bit
  23    * Program Files directory.
  24    * See https://social.msdn.microsoft.com/Forums/windowsdesktop/en-US/6f2e7920-50a9-459d-bfdd-316e459e87c0/ishelllink-getpath-returns-wrong-folder-for-64-bit-application-when-called-from-32-bit-application
  25    * for some additional discussion of this.
  26    *
  27    * @param aBinary Target file of the shortcut.
  28    * @param aArguments Arguments to set for the shortcut. May be empty.
  29    * @param aDescription The description of the shortcut. The string used here
  30    *        shows up as the hover text of the shortcut in Explorer and on the
  31    *        Taskbar (if the shortcut is pinned there).
  32    * @param aIconFile The file containing the desired icon for the shortcut. This
  33    *        can be the same file as aBinary.
  34    * @param aIconIndex The index of the in aIconFile. Note that this is 0 based index
  35    *        that IShellLinkW requires, _not_ a Resource ID that is sometimes used
  36    *        for icons.
  37    * @param aAppUserModelId The App User Model ID to set for the shortcut. This will
  38    *        affect which icon on the Taskbar the application groups with when first
  39    *        launched.
  40    * @param aShortcutFolder The special Windows folder to create the shortcut in. One of:
  41    *        CommonStartMenu, StartMenu, PublicDesktop, Desktop, or QuickLaunch.
  42    * @param aShortcutName The filename of the shortcut within aShortcutFolder.
  43    * @return The full native path to the created shortcut.
  44    *
  45    * @throws NS_ERROR_INVALID_ARG if an invalid shortcut folder is passed
  46    * @throws NS_ERROR_FILE_NOT_FOUND if the shortcut file or shortcuts log cannot be
  47    *         created or accessed
  48    * @throws NS_ERROR_FAILURE for other types of failures
  49    */
  50   [implicit_jscontext]
  51   Promise createShortcut(in nsIFile aBinary, in Array<AString> aArguments,
  52     in AString aDescription, in nsIFile aIconFile, in unsigned short aIconIndex,
  53     in AString aAppUserModelId, in AString aShortcutFolder, in AString aShortcutName);
  54
  55   /*
  56    * Searches the %USERPROFILE%\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup
  57    * folder and returns an array with the path of all shortcuts with a target matching the
  58    * current Firefox install location. The AUMID isn't required here as we are only looking
  59    * for the currently running binary, whether that's firefox.exe or the private browsing
  60    * proxy executable.
  61    *
  62    * It is possible to return an empty array if no shortcuts are found.
  63    *
  64    * @return An array of paths for all launch on login shortcuts.s
  65    *
  66    * @throws NS_ERROR_ABORT
  67    *         if instance cannot be created.
  68    * @throws NS_ERROR_FILE_NOT_FOUND
  69    *         if %USERPROFILE%\AppData\Roaming\ cannot be opened.
  70    * @throws NS_ERROR_FAILURE
  71    *         if the executable file cannot be found.
  72    * @throws NS_ERROR_FILE_UNRECOGNIZED_PATH
  73    *         if the executable file cannot be converted into a string.
  74    */
  75
  76   Array<AString> getLaunchOnLoginShortcuts();
  77
  78   /*
  79    * Pins the current application to the Windows Start Menu
  80    *
  81    * The APIs used within this function are MSIX only and
  82    * will also not work on MINGW.
  83    *
  84    * @param aCheckOnly If only testing whether pinning is possible
  85    *
  86    * @return True if the application was successfully pinned
  87    *              to the Start Menu.
  88    *
  89    * @throws NS_ERROR_NOT_AVAILABLE
  90    *         If used on a non-MSIX build
  91    * @throws NS_ERROR_NOT_IMPLEMENTED
  92    *         If used on a MinGW build
  93    * @throws NS_ERROR_NOT_SAME_THREAD
  94    *         If called off main thread
  95    * @throws NS_ERROR_FAILURE
  96    *         For Windows API failures
  97    */
  98   [implicit_jscontext]
  99   Promise pinCurrentAppToStartMenuAsync(in boolean aCheckOnly);
 100
 101   /*
 102    * Whether the current app is among Windows Start Menu pins
 103    *
 104    * @return True if pinned, false otherwise
 105    *
 106    * The APIs used within this function are MSIX only and
 107    * will also not work on MINGW.
 108    *
 109    * @throws NS_ERROR_NOT_AVAILABLE
 110    *         If used on a non-MSIX build
 111    * @throws NS_ERROR_NOT_IMPLEMENTED
 112    *         If used on a MinGW build
 113    * @throws NS_ERROR_NOT_SAME_THREAD
 114    *         If called off main thread
 115    * @throws NS_ERROR_FAILURE
 116    *         For Windows API failures
 117    */
 118   [implicit_jscontext]
 119   Promise isCurrentAppPinnedToStartMenuAsync();
 120
 121   /*
 122    * Disables the startup task corresponding to the provided taskId
 123    * to launch upon OS login. The startup task is declared
 124    * within the App Manifest.
 125    *
 126    * If the task was previously disabled by the user this function
 127    * will not re-enable it.
 128    *
 129    * The APIs used within this function are MSIX only and
 130    * will also not work on MINGW.
 131    *
 132    * @param aTaskId Target taskId to enable
 133    *
 134    * @return True if the application was successfully set up to
 135    *         launch on OS login.
 136    *
 137    * @throws NS_ERROR_NOT_AVAILABLE
 138    *         If used on a non-MSIX build
 139    * @throws NS_ERROR_NOT_IMPLEMENTED
 140    *         If used on a MinGW build
 141    * @throws NS_ERROR_NOT_SAME_THREAD
 142    *         If called off main thread
 143    * @throws NS_ERROR_FAILURE
 144    *         For other types of failures
 145    */
 146   [implicit_jscontext]
 147   Promise enableLaunchOnLoginMSIXAsync(in AString aTaskId);
 148
 149   /*
 150    * Disables the startup task corresponding to the provided taskId
 151    * to launch upon OS login. The startup task is declared
 152    * within the App Manifest.
 153    *
 154    * The APIs used within this function are MSIX only and
 155    * will also not work on MINGW.
 156    *
 157    * @param aTaskId Target taskId to disable
 158    *
 159    * @return True if the application was successfully disabled from
 160    *         launching on OS login.
 161    *
 162    * @throws NS_ERROR_NOT_AVAILABLE
 163    *         If used on a non-MSIX build
 164    * @throws NS_ERROR_NOT_IMPLEMENTED
 165    *         If used on a MinGW build
 166    * @throws NS_ERROR_NOT_SAME_THREAD
 167    *         If called off main thread
 168    * @throws NS_ERROR_FAILURE
 169    *         For other types of failures
 170    */
 171   [implicit_jscontext]
 172   Promise disableLaunchOnLoginMSIXAsync(in AString aTaskId);
 173
 174   /*
 175    * Determines if the startup task corresponding to the provided taskId to
 176    * launch upon OS login is enabled. The startup task is declared
 177    * within the App Manifest. The APIs used within this function are MSIX
 178    * only and will also not work on MINGW.
 179    *
 180    * If the user has disabled the application from launching on login, it
 181    * cannot be re-enabled by the application.
 182    *
 183    * @param aTaskId Target taskId to check status of
 184    *
 185    * @return 0/1/2/3 if the application's OS launch on login is
 186              disabled in settings / disabled / enabled / enabled by policy
 187    *
 188    * @throws NS_ERROR_NOT_AVAILABLE
 189    *         If used on a non-MSIX build
 190    * @throws NS_ERROR_NOT_IMPLEMENTED
 191    *         If used on a MinGW build
 192    * @throws NS_ERROR_NOT_SAME_THREAD
 193    *         If called off main thread
 194    * @throws NS_ERROR_FAILURE
 195    *         For other types of failures
 196    */
 197
 198   cenum LaunchOnLoginEnabledEnumerator : 8 {
 199     LAUNCH_ON_LOGIN_DISABLED_BY_SETTINGS = 0,
 200     LAUNCH_ON_LOGIN_DISABLED = 1,
 201     LAUNCH_ON_LOGIN_ENABLED = 2,
 202     LAUNCH_ON_LOGIN_ENABLED_BY_POLICY = 3,
 203   };
 204
 205   [implicit_jscontext]
 206   Promise getLaunchOnLoginEnabledMSIXAsync(in AString aTaskId);
 207
 208   /*
 209    * Pin the current app to the taskbar. If aPrivateBrowsing is true, the
 210    * Private Browsing version of the app (with a different icon and launch
 211    * arguments) will be pinned instead.
 212    *
 213    * This MUST only be used in response to an active request from the user.
 214    *
 215    * If it exists, uses an existing shortcut on the Desktop or Start Menu,
 216    * which would have been created by the installer (for All Users or
 217    * Current User). If none can be found, one will be created with the correct
 218    * AUMID for proper launching and grouping.
 219    *
 220    * NOTE: It is possible for the shortcut match to fail even when a
 221    * shortcut refers to the current executable, if the paths differ due
 222    * to e.g. symlinks. This should be rare.
 223    *
 224    * This will definitely fail on an OS before Windows 10 build 1809
 225    * (October 2018 Update).
 226    *
 227    * NOTE: Can only run on the main thread, but the actual work occurs on a
 228    * background thread.
 229    *
 230    * @throws NS_ERROR_NOT_SAME_THREAD
 231    *         if called off main thread.
 232    * @throws NS_ERROR_NOT_AVAILABLE
 233    *         if OS is not at least Windows 10 build 1809, or if creating the
 234    *         Taskband Pin object fails
 235    * @throws NS_ERROR_FAILURE
 236    *         for unexpected errors
 237    *
 238    * @rejects NS_ERROR_FILE_NOT_FOUND
 239    *         if a shortcut matching this app's AUMID and exe path wasn't found
 240    *
 241    * @returns {Promise<void>} A promise that resolves to |undefined| if
 242    *                          successful or rejects with an nserror.
 243    */
 244   [implicit_jscontext]
 245   Promise pinCurrentAppToTaskbarAsync(in boolean aPrivateBrowsing);
 246
 247   /*
 248    * Do a dry run of pinCurrentAppToTaskbar().
 249    *
 250    * NOTE: Can only be run on the main thread, but the actual work occurs on a
 251    * background thread.
 252    *
 253    * This does all the same checks and setup, throws the same errors, but doesn't
 254    * do the final step of creating the pin.
 255    *
 256    * @throws same as pinCurrentAppToTaskbarAsync()
 257    * @rejects same as pinCurrentAppToTaskbarAsync()
 258    * @returns same as pinCurrentAppToTaskbarAsync()
 259    */
 260   [implicit_jscontext]
 261   Promise checkPinCurrentAppToTaskbarAsync(in boolean aPrivateBrowsing);
 262
 263   /*
 264    * Search for the current executable among taskbar pins
 265    *
 266    * NOTE: Can only be run on the main thread, but the actual work occurs on a
 267    * background thread.
 268    *
 269    * NOTE: It is possible for the check to fail even when a taskbar pin refers
 270    * to this executable, if the paths differ due to e.g. symlinks.
 271    * It is also possible for the check to succeed with a shortcut that doesn't
 272    * actually appear on the taskbar.
 273    * These cases should be rare.
 274    *
 275    * @return Promise that always resolves, true if pinned, false otherwise
 276    * @throws NS_ERROR_NOT_SAME_THREAD if not run on the main thread
 277    *
 278    */
 279   [implicit_jscontext]
 280   Promise isCurrentAppPinnedToTaskbarAsync(in AString aumid);
 281
 282   /*
 283    * Similar to createShortcut except it removes most of the checking in that
 284    * function that ensures we are pinning a Firefox executable instead allowing
 285    * any shortcut to be pinned.
 286    *
 287    * This function should not be called unless it is certain that it's
 288    * necessary given how few checks there are within.
 289    * @param  aShortcutPath
 290    *         A path to the .lnk file that should be pinned to the taskbar.
 291    * @throws NS_ERROR_FAILURE
 292    *         If the COM service could not be initialized
 293    * @throws NS_ERROR_FILE_NOT_FOUND
 294    *         If aShortcutPath cannot be found
 295    * @throws NS_ERROR_NOT_AVAILABLE
 296    *         If the taskbar pinning service cannot be initialized
 297    * @throws NS_ERROR_FILE_ACCESS_DENIED
 298    *         If the taskbar pins cannot be modified
 299    */
 300   void pinShortcutToTaskbar(in AString aShortcutPath);
 301
 302   /*
 303    * This function is a counterpart to pinShortcutToTaskbar and allows
 304    * the unpinning of any shortcut, including non-Firefox executables,
 305    * without the checks of createShortcut.
 306    *
 307    * This function should not be called unless it is certain that it's
 308    * necessary given how few checks there are within.
 309    * @param  aShortcutPath
 310    *         A path to the .lnk file that should be pinned to the taskbar.
 311    * @throws NS_ERROR_FAILURE
 312    *         If the COM service could not be initialized
 313    * @throws NS_ERROR_FILE_NOT_FOUND
 314    *         If aShortcutPath cannot be found
 315    * @throws NS_ERROR_NOT_AVAILABLE
 316    *         If the taskbar pinning service cannot be initialized
 317    * @throws NS_ERROR_FILE_ACCESS_DENIED
 318    *         If the taskbar pins cannot be modified
 319    */
 320   void unpinShortcutFromTaskbar(in AString aShortcutPath);
 321
 322
 323   /**
 324    * Gets the full path of a taskbar tab shortcut.
 325    *
 326    * @param  aShortcutName
 327    *         The name of the taskbar tab shortcut, excluding the file extension.
 328    * @throws NS_ERROR_FAILURE
 329    *         If the user token cannot be found.
 330    * @throws NS_ERROR_ABORT
 331    *         If converting the sid to a string fails.
 332    *
 333    * @return The full path of the taskbar tab shortcut
 334    */
 335   AString getTaskbarTabShortcutPath(in AString aShortcutName);
 336
 337   /*
 338    * Searches the %USERPROFILE%\AppData\Roaming\Microsoft\Windows\Start
 339    * Menu\Programs folder and returns an array with the path of all
 340    * shortcuts with a target matching the current Firefox install location
 341    * and the -taskbar-tab argument.
 342    *
 343    * It is possible to return an empty array if no shortcuts are found.
 344    *
 345    * @return An array of paths for all taskbar tab shortcuts.
 346    *
 347    * @throws NS_ERROR_NOT_IMPLEMENTED
 348    *         if run on a MinGW compilation
 349    * @throws NS_ERROR_ABORT
 350    *         if instance cannot be created.
 351    * @throws NS_ERROR_FILE_NOT_FOUND
 352    *         if %USERPROFILE%\AppData\Roaming\ cannot be opened.
 353    * @throws NS_ERROR_FAILURE
 354    *         if the executable file cannot be found.
 355    * @throws NS_ERROR_FILE_UNRECOGNIZED_PATH
 356    *         if the executable file cannot be converted into a string.
 357    */
 358   Array<AString> getTaskbarTabPins();
 359
 360   /*
 361    * Determine where a given shortcut likely appears in the shell.
 362    *
 363    * Returns one of:
 364    * - "StartMenu" or "StartMenuPrivate", Current User or All Users Start
 365    *    Menu, including pins
 366    * - "Desktop" or "DesktopPrivate", Current User or All Users Desktop
 367    * - "Taskbar" or "TaskbarPrivate", Taskbar Pins
 368    * - "" otherwise
 369    *
 370    * If a Private Browsing shortcut was used to launch, the "Private"
 371    * variant of one of the above entries will be returned.
 372    *
 373    * NOTE: This tries to avoid I/O, so paths are compared directly as
 374    * strings, which may not be accurate in all cases. It is intended
 375    * for noncritical telemetry use.
 376    */
 377   AString classifyShortcut(in AString aPath);
 378
 379   [implicit_jscontext]
 380   Promise hasMatchingShortcut(in AString aAUMID, in boolean aPrivateBrowsing);
 381
 382   /*
 383    * Check if setDefaultBrowserUserChoice() is expected to succeed.
 384    *
 385    * This checks the ProgIDs for this installation, and the hash of the existing
 386    * UserChoice association.
 387    *
 388    * @return true if the check succeeds, false otherwise.
 389    */
 390   boolean canSetDefaultBrowserUserChoice();
 391
 392   /*
 393    * checkAllProgIDsExist() and checkBrowserUserChoiceHashes() are components
 394    * of canSetDefaultBrowserUserChoice(), broken out for telemetry purposes.
 395    *
 396    * @return true if the check succeeds, false otherwise.
 397    */
 398   boolean checkAllProgIDsExist();
 399   boolean checkBrowserUserChoiceHashes();
 400
 401   /*
 402    * Determines whether or not Firefox is the "Default Handler", i.e.,
 403    * is registered to handle, the given file extension (like ".pdf")
 404    * or protocol (like "https").
 405    */
 406   boolean isDefaultHandlerFor(in AString aFileExtensionOrProtocol);
 407
 408
 409   /*
 410    * Return the Windows ProgID currently registered to handle the gven
 411    * file extension (like ".pdf") or protocol (like "https").
 412    *
 413    * @return string ProgID, or "" when no association is registered.
 414    * @throws NS_ERROR_FAILURE when the file extension or protocol
 415    *         cannot be determined.
 416    */
 417   AString queryCurrentDefaultHandlerFor(in AString aFileExtensionOrProtocol);
 418 };