diff options
Diffstat (limited to 'browser/components/shell/nsIWindowsShellService.idl')
| -rw-r--r-- | browser/components/shell/nsIWindowsShellService.idl | 288 |
1 files changed, 288 insertions, 0 deletions
diff --git a/browser/components/shell/nsIWindowsShellService.idl b/browser/components/shell/nsIWindowsShellService.idl new file mode 100644 index 0000000000..13c824f39c --- /dev/null +++ b/browser/components/shell/nsIWindowsShellService.idl @@ -0,0 +1,288 @@ +/* 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 nsIFile; + +[scriptable, uuid(fb9b59db-5a91-4e67-92b6-35e7d6e6d3fd)] +interface nsIWindowsShellService : nsISupports +{ + /* + * Creates a new shortcut (.lnk) file. This shortcut will be recorded in + * a new shortcuts log file located in %PROGRAMDATA%\Mozilla-1de4eec8-1241-4177-a864-e594e8d1fb38 + * that is named after the currently running application and current user, eg: + * Firefox_user123_shortcuts.ini. + * + * For reasons that we haven't been able to pin down, these shortcuts get created with + * extra metadata on them (KnownFolderDataBlock, SpecialFolderDataBlock) that cause + * the Windows ShellLink classes to improperly read their target path with certain + * parameters. This causes any 32-bit programs that read the links (such as our + * installer and uninstaller) to think that 64-bit installs are located in the 32-bit + * Program Files directory. + * 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 + * for some additional discussion of this. + * + * @param aBinary Target file of the shortcut. + * @param aArguments Arguments to set for the shortcut. May be empty. + * @param aDescription The description of the shortcut. The string used here + * shows up as the hover text of the shortcut in Explorer and on the + * Taskbar (if the shortcut is pinned there). + * @param aIconFile The file containing the desired icon for the shortcut. This + * can be the same file as aBinary. + * @param aIconIndex The index of the in aIconFile. Note that this is 0 based index + * that IShellLinkW requires, _not_ a Resource ID that is sometimes used + * for icons. + * @param aAppUserModelId The App User Model ID to set for the shortcut. This will + * affect which icon on the Taskbar the application groups with when first + * launched. + * @param aShortcutFolder The special Windows folder to create the shortcut in. One of: + * CommonStartMenu, StartMenu, PublicDesktop, Desktop, or QuickLaunch. + * @param aShortcutName The filename of the shortcut within aShortcutFolder. + * @return The full native path to the created shortcut. + * + * @throws NS_ERROR_INVALID_ARG if an invalid shortcut folder is passed + * @throws NS_ERROR_FILE_NOT_FOUND if the shortcut file or shortcuts log cannot be + * created or accessed + * @throws NS_ERROR_FAILURE for other types of failures + */ + [implicit_jscontext] + Promise createShortcut(in nsIFile aBinary, in Array<AString> aArguments, + in AString aDescription, in nsIFile aIconFile, in unsigned short aIconIndex, + in AString aAppUserModelId, in AString aShortcutFolder, in AString aShortcutName); + + /* + * Searches the %USERPROFILE%\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup + * folder and returns an array with the path of all shortcuts with a target matching the + * current Firefox install location. The AUMID isn't required here as we are only looking + * for the currently running binary, whether that's firefox.exe or the private browsing + * proxy executable. + * + * It is possible to return an empty array if no shortcuts are found. + * + * @return An array of paths for all launch on login shortcuts.s + * + * @throws NS_ERROR_ABORT + * if instance cannot be created. + * @throws NS_ERROR_FILE_NOT_FOUND + * if %USERPROFILE%\AppData\Roaming\ cannot be opened. + * @throws NS_ERROR_FAILURE + * if the executable file cannot be found. + * @throws NS_ERROR_FILE_UNRECOGNIZED_PATH + * if the executable file cannot be converted into a string. + */ + + Array<AString> getLaunchOnLoginShortcuts(); + + /* + * Pin the current app to the taskbar. If aPrivateBrowsing is true, the + * Private Browsing version of the app (with a different icon and launch + * arguments) will be pinned instead. + * + * This MUST only be used in response to an active request from the user. + * + * If it exists, uses an existing shortcut on the Desktop or Start Menu, + * which would have been created by the installer (for All Users or + * Current User). If none can be found, one will be created with the correct + * AUMID for proper launching and grouping. + * + * NOTE: It is possible for the shortcut match to fail even when a + * shortcut refers to the current executable, if the paths differ due + * to e.g. symlinks. This should be rare. + * + * This will definitely fail on an OS before Windows 10 build 1809 + * (October 2018 Update). + * + * NOTE: Can only run on the main thread, but the actual work occurs on a + * background thread. + * + * @throws NS_ERROR_NOT_SAME_THREAD + * if called off main thread. + * @throws NS_ERROR_NOT_AVAILABLE + * if OS is not at least Windows 10 build 1809, or if creating the + * Taskband Pin object fails + * @throws NS_ERROR_FAILURE + * for unexpected errors + * + * @rejects NS_ERROR_FILE_NOT_FOUND + * if a shortcut matching this app's AUMID and exe path wasn't found + * + * @returns {Promise<void>} A promise that resolves to |undefined| if + * successful or rejects with an nserror. + */ + [implicit_jscontext] + Promise pinCurrentAppToTaskbarAsync(in bool aPrivateBrowsing); + + /* + * Do a dry run of pinCurrentAppToTaskbar(). + * + * NOTE: Can only be run on the main thread, but the actual work occurs on a + * background thread. + * + * This does all the same checks and setup, throws the same errors, but doesn't + * do the final step of creating the pin. + * + * @throws same as pinCurrentAppToTaskbarAsync() + * @rejects same as pinCurrentAppToTaskbarAsync() + * @returns same as pinCurrentAppToTaskbarAsync() + */ + [implicit_jscontext] + Promise checkPinCurrentAppToTaskbarAsync(in bool aPrivateBrowsing); + + /* + * Search for the current executable among taskbar pins + * + * NOTE: Can only be run on the main thread, but the actual work occurs on a + * background thread. + * + * NOTE: It is possible for the check to fail even when a taskbar pin refers + * to this executable, if the paths differ due to e.g. symlinks. + * It is also possible for the check to succeed with a shortcut that doesn't + * actually appear on the taskbar. + * These cases should be rare. + * + * @return Promise that always resolves, true if pinned, false otherwise + * @throws NS_ERROR_NOT_SAME_THREAD if not run on the main thread + * + */ + [implicit_jscontext] + Promise isCurrentAppPinnedToTaskbarAsync(in AString aumid); + + /* + * Similar to createShortcut except it removes most of the checking in that + * function that ensures we are pinning a Firefox executable instead allowing + * any shortcut to be pinned. + * + * This function should not be called unless it is certain that it's + * necessary given how few checks there are within. + * @param aShortcutPath + * A path to the .lnk file that should be pinned to the taskbar. + * @throws NS_ERROR_FAILURE + * If the COM service could not be initialized + * @throws NS_ERROR_FILE_NOT_FOUND + * If aShortcutPath cannot be found + * @throws NS_ERROR_NOT_AVAILABLE + * If the taskbar pinning service cannot be initialized + * @throws NS_ERROR_FILE_ACCESS_DENIED + * If the taskbar pins cannot be modified + */ + void pinShortcutToTaskbar(in AString aShortcutPath); + + /* + * This function is a counterpart to pinShortcutToTaskbar and allows + * the unpinning of any shortcut, including non-Firefox executables, + * without the checks of createShortcut. + * + * This function should not be called unless it is certain that it's + * necessary given how few checks there are within. + * @param aShortcutPath + * A path to the .lnk file that should be pinned to the taskbar. + * @throws NS_ERROR_FAILURE + * If the COM service could not be initialized + * @throws NS_ERROR_FILE_NOT_FOUND + * If aShortcutPath cannot be found + * @throws NS_ERROR_NOT_AVAILABLE + * If the taskbar pinning service cannot be initialized + * @throws NS_ERROR_FILE_ACCESS_DENIED + * If the taskbar pins cannot be modified + */ + void unpinShortcutFromTaskbar(in AString aShortcutPath); + + + /** + * Gets the full path of a taskbar tab shortcut. + * + * @param aShortcutName + * The name of the taskbar tab shortcut, excluding the file extension. + * @throws NS_ERROR_FAILURE + * If the user token cannot be found. + * @throws NS_ERROR_ABORT + * If converting the sid to a string fails. + * + * @return The full path of the taskbar tab shortcut + */ + AString getTaskbarTabShortcutPath(in AString aShortcutName); + + /* + * Searches the %USERPROFILE%\AppData\Roaming\Microsoft\Windows\Start + * Menu\Programs folder and returns an array with the path of all + * shortcuts with a target matching the current Firefox install location + * and the -taskbar-tab argument. + * + * It is possible to return an empty array if no shortcuts are found. + * + * @return An array of paths for all taskbar tab shortcuts. + * + * @throws NS_ERROR_NOT_IMPLEMENTED + * if run on a MinGW compilation + * @throws NS_ERROR_ABORT + * if instance cannot be created. + * @throws NS_ERROR_FILE_NOT_FOUND + * if %USERPROFILE%\AppData\Roaming\ cannot be opened. + * @throws NS_ERROR_FAILURE + * if the executable file cannot be found. + * @throws NS_ERROR_FILE_UNRECOGNIZED_PATH + * if the executable file cannot be converted into a string. + */ + Array<AString> getTaskbarTabPins(); + + /* + * Determine where a given shortcut likely appears in the shell. + * + * Returns one of: + * - "StartMenu" or "StartMenuPrivate", Current User or All Users Start + * Menu, including pins + * - "Desktop" or "DesktopPrivate", Current User or All Users Desktop + * - "Taskbar" or "TaskbarPrivate", Taskbar Pins + * - "" otherwise + * + * If a Private Browsing shortcut was used to launch, the "Private" + * variant of one of the above entries will be returned. + * + * NOTE: This tries to avoid I/O, so paths are compared directly as + * strings, which may not be accurate in all cases. It is intended + * for noncritical telemetry use. + */ + AString classifyShortcut(in AString aPath); + + [implicit_jscontext] + Promise hasMatchingShortcut(in AString aAUMID, in bool aPrivateBrowsing); + + /* + * Check if setDefaultBrowserUserChoice() is expected to succeed. + * + * This checks the ProgIDs for this installation, and the hash of the existing + * UserChoice association. + * + * @return true if the check succeeds, false otherwise. + */ + bool canSetDefaultBrowserUserChoice(); + + /* + * checkAllProgIDsExist() and checkBrowserUserChoiceHashes() are components + * of canSetDefaultBrowserUserChoice(), broken out for telemetry purposes. + * + * @return true if the check succeeds, false otherwise. + */ + bool checkAllProgIDsExist(); + bool checkBrowserUserChoiceHashes(); + + /* + * Determines whether or not Firefox is the "Default Handler", i.e., + * is registered to handle, the given file extension (like ".pdf") + * or protocol (like "https"). + */ + boolean isDefaultHandlerFor(in AString aFileExtensionOrProtocol); + + + /* + * Return the Windows ProgID currently registered to handle the gven + * file extension (like ".pdf") or protocol (like "https"). + * + * @return string ProgID, or "" when no association is registered. + * @throws NS_ERROR_FAILURE when the file extension or protocol + * cannot be determined. + */ + AString queryCurrentDefaultHandlerFor(in AString aFileExtensionOrProtocol); +}; |