173 lines
7.4 KiB
Text
173 lines
7.4 KiB
Text
/* 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
|
|
*/
|
|
AString 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);
|
|
|
|
/*
|
|
* 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: This method probably shouldn't be used on the main thread, it
|
|
* performs blocking disk I/O.
|
|
*
|
|
* 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 is fully supported on Windows 7, 8, and 11. On Windows 10, it will
|
|
* definitely fail on a version prior to build 1809 (October 2018 Update).
|
|
*
|
|
* @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_FILE_NOT_FOUND
|
|
* if a shortcut matching this app's AUMID and exe path wasn't found
|
|
* @throws NS_ERROR_FAILURE
|
|
* for unexpected errors
|
|
*/
|
|
void pinCurrentAppToTaskbar(in bool aPrivateBrowsing);
|
|
|
|
/*
|
|
* Do a dry run of pinCurrentAppToTaskbar()
|
|
*
|
|
* This does all the same checks and setup, throws the same errors, but doesn't
|
|
* do the final step of creating the pin.
|
|
*
|
|
* NOTE: This method probably shouldn't be used on the main thread, it
|
|
* performs blocking disk I/O.
|
|
*
|
|
* @throws same as pinCurrentAppToTaskbar()
|
|
*/
|
|
void checkPinCurrentAppToTaskbar(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);
|
|
|
|
/*
|
|
* 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);
|
|
|
|
/*
|
|
* 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);
|
|
};
|