1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
/* 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);
/*
* 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 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).
*
* 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);
/*
* 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);
};
|
