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/. */
5 #include
"nsISupports.idl"
9 [scriptable
, uuid(fb9b59db
-5a91
-4e67
-92b6
-35e7d6e6d3fd
)]
10 interface nsIWindowsShellService
: nsISupports
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.
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.
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
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
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.
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
48 * @throws NS_ERROR_FAILURE for other types of failures
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
);
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
62 * It is possible to return an empty array if no shortcuts are found.
64 * @return An array of paths for all launch on login shortcuts.s
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.
76 Array
<AString
> getLaunchOnLoginShortcuts
();
79 * Pins the current application to the Windows Start Menu
81 * The APIs used within this function are MSIX only and
82 * will also not work on MINGW.
84 * @param aCheckOnly If only testing whether pinning is possible
86 * @return True if the application was successfully pinned
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
99 Promise pinCurrentAppToStartMenuAsync
(in boolean aCheckOnly
);
102 * Whether the current app is among Windows Start Menu pins
104 * @return True if pinned, false otherwise
106 * The APIs used within this function are MSIX only and
107 * will also not work on MINGW.
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
119 Promise isCurrentAppPinnedToStartMenuAsync
();
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.
126 * If the task was previously disabled by the user this function
127 * will not re-enable it.
129 * The APIs used within this function are MSIX only and
130 * will also not work on MINGW.
132 * @param aTaskId Target taskId to enable
134 * @return True if the application was successfully set up to
135 * launch on OS login.
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
147 Promise enableLaunchOnLoginMSIXAsync
(in AString aTaskId
);
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.
154 * The APIs used within this function are MSIX only and
155 * will also not work on MINGW.
157 * @param aTaskId Target taskId to disable
159 * @return True if the application was successfully disabled from
160 * launching on OS login.
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
172 Promise disableLaunchOnLoginMSIXAsync
(in AString aTaskId
);
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.
180 * If the user has disabled the application from launching on login, it
181 * cannot be re-enabled by the application.
183 * @param aTaskId Target taskId to check status of
185 * @return 0/1/2/3 if the application's OS launch on login is
186 disabled in settings / disabled / enabled / enabled by policy
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
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,
206 Promise getLaunchOnLoginEnabledMSIXAsync
(in AString aTaskId
);
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.
213 * This MUST only be used in response to an active request from the user.
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.
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.
224 * This will definitely fail on an OS before Windows 10 build 1809
225 * (October 2018 Update).
227 * NOTE: Can only run on the main thread, but the actual work occurs on a
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
238 * @rejects NS_ERROR_FILE_NOT_FOUND
239 * if a shortcut matching this app's AUMID and exe path wasn't found
241 * @returns {Promise<void>} A promise that resolves to |undefined| if
242 * successful or rejects with an nserror.
245 Promise pinCurrentAppToTaskbarAsync
(in boolean aPrivateBrowsing
);
248 * Do a dry run of pinCurrentAppToTaskbar().
250 * NOTE: Can only be run on the main thread, but the actual work occurs on a
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.
256 * @throws same as pinCurrentAppToTaskbarAsync()
257 * @rejects same as pinCurrentAppToTaskbarAsync()
258 * @returns same as pinCurrentAppToTaskbarAsync()
261 Promise checkPinCurrentAppToTaskbarAsync
(in boolean aPrivateBrowsing
);
264 * Search for the current executable among taskbar pins
266 * NOTE: Can only be run on the main thread, but the actual work occurs on a
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.
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
280 Promise isCurrentAppPinnedToTaskbarAsync
(in AString aumid
);
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.
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
300 void pinShortcutToTaskbar
(in AString aShortcutPath
);
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.
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
320 void unpinShortcutFromTaskbar
(in AString aShortcutPath
);
324 * Gets the full path of a taskbar tab shortcut.
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.
333 * @return The full path of the taskbar tab shortcut
335 AString getTaskbarTabShortcutPath
(in AString aShortcutName
);
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.
343 * It is possible to return an empty array if no shortcuts are found.
345 * @return An array of paths for all taskbar tab shortcuts.
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.
358 Array
<AString
> getTaskbarTabPins
();
361 * Determine where a given shortcut likely appears in the shell.
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
370 * If a Private Browsing shortcut was used to launch, the "Private"
371 * variant of one of the above entries will be returned.
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.
377 AString classifyShortcut
(in AString aPath
);
380 Promise hasMatchingShortcut
(in AString aAUMID
, in boolean aPrivateBrowsing
);
383 * Check if setDefaultBrowserUserChoice() is expected to succeed.
385 * This checks the ProgIDs for this installation, and the hash of the existing
386 * UserChoice association.
388 * @return true if the check succeeds, false otherwise.
390 boolean canSetDefaultBrowserUserChoice
();
393 * checkAllProgIDsExist() and checkBrowserUserChoiceHashes() are components
394 * of canSetDefaultBrowserUserChoice(), broken out for telemetry purposes.
396 * @return true if the check succeeds, false otherwise.
398 boolean checkAllProgIDsExist
();
399 boolean checkBrowserUserChoiceHashes
();
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").
406 boolean isDefaultHandlerFor
(in AString aFileExtensionOrProtocol
);
410 * Return the Windows ProgID currently registered to handle the gven
411 * file extension (like ".pdf") or protocol (like "https").
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.
417 AString queryCurrentDefaultHandlerFor
(in AString aFileExtensionOrProtocol
);