1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 // This file declares methods that are useful for integrating Chrome in
6 // Windows shell. These methods are all static and currently part of
9 #ifndef CHROME_INSTALLER_UTIL_SHELL_UTIL_H_
10 #define CHROME_INSTALLER_UTIL_SHELL_UTIL_H_
17 #include "base/basictypes.h"
18 #include "base/files/file_path.h"
19 #include "base/logging.h"
20 #include "base/strings/string16.h"
21 #include "chrome/installer/util/work_item_list.h"
23 class BrowserDistribution;
25 // This is a utility class that provides common shell integration methods
26 // that can be used by installer as well as Chrome.
29 // Input to any methods that make changes to OS shell.
31 CURRENT_USER = 0x1, // Make any shell changes only at the user level
32 SYSTEM_LEVEL = 0x2 // Make any shell changes only at the system level
35 // Chrome's default handler state for a given protocol.
42 // Typical shortcut directories. Resolved in GetShortcutPath().
43 // Also used in ShortcutLocationIsSupported().
44 enum ShortcutLocation {
45 SHORTCUT_LOCATION_DESKTOP,
46 SHORTCUT_LOCATION_QUICK_LAUNCH,
47 SHORTCUT_LOCATION_START_MENU,
48 SHORTCUT_LOCATION_TASKBAR_PINS, // base::win::VERSION_WIN7 +
49 SHORTCUT_LOCATION_APP_SHORTCUTS, // base::win::VERSION_WIN8 +
52 enum ShortcutOperation {
53 // Create a new shortcut (overwriting if necessary).
54 SHELL_SHORTCUT_CREATE_ALWAYS,
55 // Create the per-user shortcut only if its system-level equivalent (with
56 // the same name) is not present.
57 SHELL_SHORTCUT_CREATE_IF_NO_SYSTEM_LEVEL,
58 // Overwrite an existing shortcut (fail if the shortcut doesn't exist).
59 // If the arguments are not specified on the new shortcut, keep the old
60 // shortcut's arguments.
61 SHELL_SHORTCUT_REPLACE_EXISTING,
62 // Update specified properties only on an existing shortcut.
63 SHELL_SHORTCUT_UPDATE_EXISTING,
66 // Properties for shortcuts. Properties set will be applied to
67 // the shortcut on creation/update. On update, unset properties are ignored;
68 // on create (and replaced) unset properties might have a default value (see
69 // individual property setters below for details).
70 // Callers are encouraged to use the setters provided which take care of
71 // setting |options| as desired.
72 struct ShortcutProperties {
73 enum IndividualProperties {
74 PROPERTIES_TARGET = 1 << 0,
75 PROPERTIES_ARGUMENTS = 1 << 1,
76 PROPERTIES_DESCRIPTION = 1 << 2,
77 PROPERTIES_ICON = 1 << 3,
78 PROPERTIES_APP_ID = 1 << 4,
79 PROPERTIES_SHORTCUT_NAME = 1 << 5,
80 PROPERTIES_DUAL_MODE = 1 << 6,
83 explicit ShortcutProperties(ShellChange level_in)
84 : level(level_in), icon_index(0), dual_mode(false),
85 pin_to_taskbar(false), options(0U) {}
87 // Sets the target executable to launch from this shortcut.
88 // This is mandatory when creating a shortcut.
89 void set_target(const base::FilePath& target_in) {
91 options |= PROPERTIES_TARGET;
94 // Sets the arguments to be passed to |target| when launching from this
96 // The length of this string must be less than MAX_PATH.
97 void set_arguments(const string16& arguments_in) {
98 // Size restriction as per MSDN at
99 // http://msdn.microsoft.com/library/windows/desktop/bb774954.aspx.
100 DCHECK(arguments_in.length() < MAX_PATH);
101 arguments = arguments_in;
102 options |= PROPERTIES_ARGUMENTS;
105 // Sets the localized description of the shortcut.
106 // The length of this string must be less than MAX_PATH.
107 void set_description(const string16& description_in) {
108 // Size restriction as per MSDN at
109 // http://msdn.microsoft.com/library/windows/desktop/bb774955.aspx.
110 DCHECK(description_in.length() < MAX_PATH);
111 description = description_in;
112 options |= PROPERTIES_DESCRIPTION;
115 // Sets the path to the icon (icon_index set to 0).
116 // icon index unless otherwise specified in master_preferences).
117 void set_icon(const base::FilePath& icon_in, int icon_index_in) {
119 icon_index = icon_index_in;
120 options |= PROPERTIES_ICON;
123 // Sets the app model id for the shortcut (Win7+).
124 void set_app_id(const string16& app_id_in) {
126 options |= PROPERTIES_APP_ID;
129 // Forces the shortcut's name to |shortcut_name_in|.
130 // Default: the current distribution's GetShortcutName(SHORTCUT_CHROME).
131 // The ".lnk" extension will automatically be added to this name.
132 void set_shortcut_name(const string16& shortcut_name_in) {
133 shortcut_name = shortcut_name_in;
134 options |= PROPERTIES_SHORTCUT_NAME;
137 // Sets whether this is a dual mode shortcut (Win8+).
138 // NOTE: Only the default (no arguments and default browser appid) browser
139 // shortcut in the Start menu (Start screen on Win8+) should be made dual
141 void set_dual_mode(bool dual_mode_in) {
142 dual_mode = dual_mode_in;
143 options |= PROPERTIES_DUAL_MODE;
146 // Sets whether to pin this shortcut to the taskbar after creating it
147 // (ignored if the shortcut is only being updated).
148 // Note: This property doesn't have a mask in |options|.
149 void set_pin_to_taskbar(bool pin_to_taskbar_in) {
150 pin_to_taskbar = pin_to_taskbar_in;
153 bool has_target() const {
154 return (options & PROPERTIES_TARGET) != 0;
157 bool has_arguments() const {
158 return (options & PROPERTIES_ARGUMENTS) != 0;
161 bool has_description() const {
162 return (options & PROPERTIES_DESCRIPTION) != 0;
165 bool has_icon() const {
166 return (options & PROPERTIES_ICON) != 0;
169 bool has_app_id() const {
170 return (options & PROPERTIES_APP_ID) != 0;
173 bool has_shortcut_name() const {
174 return (options & PROPERTIES_SHORTCUT_NAME) != 0;
177 bool has_dual_mode() const {
178 return (options & PROPERTIES_DUAL_MODE) != 0;
181 // The level to install this shortcut at (CURRENT_USER for a per-user
182 // shortcut and SYSTEM_LEVEL for an all-users shortcut).
185 base::FilePath target;
187 string16 description;
191 string16 shortcut_name;
194 // Bitfield made of IndividualProperties. Properties set in |options| will
195 // be used to create/update the shortcut, others will be ignored on update
196 // and possibly replaced by default values on create (see individual
197 // property setters above for details on default values).
201 // Relative path of the URL Protocol registry entry (prefixed with '\').
202 static const wchar_t* kRegURLProtocol;
204 // Relative path of DefaultIcon registry entry (prefixed with '\').
205 static const wchar_t* kRegDefaultIcon;
207 // Relative path of "shell" registry key.
208 static const wchar_t* kRegShellPath;
210 // Relative path of shell open command in Windows registry
211 // (i.e. \\shell\\open\\command).
212 static const wchar_t* kRegShellOpen;
214 // Relative path of registry key under which applications need to register
215 // to control Windows Start menu links.
216 static const wchar_t* kRegStartMenuInternet;
218 // Relative path of Classes registry entry under which file associations
219 // are added on Windows.
220 static const wchar_t* kRegClasses;
222 // Relative path of RegisteredApplications registry entry under which
223 // we add Chrome as a Windows application
224 static const wchar_t* kRegRegisteredApplications;
226 // The key path and key name required to register Chrome on Windows such
227 // that it can be launched from Start->Run just by name (chrome.exe).
228 static const wchar_t* kAppPathsRegistryKey;
229 static const wchar_t* kAppPathsRegistryPathName;
231 // Registry path that stores url associations on Vista.
232 static const wchar_t* kRegVistaUrlPrefs;
234 // File extensions that Chrome registers itself as the default handler
235 // for when the user makes Chrome the default browser.
236 static const wchar_t* kDefaultFileAssociations[];
238 // File extensions that Chrome registers itself as being capable of
240 static const wchar_t* kPotentialFileAssociations[];
242 // Protocols that Chrome registers itself as the default handler for
243 // when the user makes Chrome the default browser.
244 static const wchar_t* kBrowserProtocolAssociations[];
246 // Protocols that Chrome registers itself as being capable of handling.
247 static const wchar_t* kPotentialProtocolAssociations[];
249 // Registry value name that is needed for ChromeHTML ProgId
250 static const wchar_t* kRegUrlProtocol;
252 // Relative registry path from \Software\Classes\ChromeHTML to the ProgId
253 // Application definitions.
254 static const wchar_t* kRegApplication;
256 // Registry value name for the AppUserModelId of an application.
257 static const wchar_t* kRegAppUserModelId;
259 // Registry value name for the description of an application.
260 static const wchar_t* kRegApplicationDescription;
262 // Registry value name for an application's name.
263 static const wchar_t* kRegApplicationName;
265 // Registry value name for the path to an application's icon.
266 static const wchar_t* kRegApplicationIcon;
268 // Registry value name for an application's company.
269 static const wchar_t* kRegApplicationCompany;
271 // Relative path of ".exe" registry key.
272 static const wchar_t* kRegExePath;
274 // Registry value name of the open verb.
275 static const wchar_t* kRegVerbOpen;
277 // Registry value name of the opennewwindow verb.
278 static const wchar_t* kRegVerbOpenNewWindow;
280 // Registry value name of the run verb.
281 static const wchar_t* kRegVerbRun;
283 // Registry value name for command entries.
284 static const wchar_t* kRegCommand;
286 // Registry value name for the DelegateExecute verb handler.
287 static const wchar_t* kRegDelegateExecute;
289 // Registry value name for the OpenWithProgids entry for file associations.
290 static const wchar_t* kRegOpenWithProgids;
292 // Returns true if |chrome_exe| is registered in HKLM with |suffix|.
293 // Note: This only checks one deterministic key in HKLM for |chrome_exe| and
294 // doesn't otherwise validate a full Chrome install in HKLM.
295 static bool QuickIsChromeRegisteredInHKLM(BrowserDistribution* dist,
296 const string16& chrome_exe,
297 const string16& suffix);
299 // Returns true if the current Windows version supports the presence of
300 // shortcuts at |location|.
301 static bool ShortcutLocationIsSupported(ShellUtil::ShortcutLocation location);
303 // Sets |path| to the path for a shortcut at the |location| desired for the
304 // given |level| (CURRENT_USER for per-user path and SYSTEM_LEVEL for
306 // Returns false on failure.
307 static bool GetShortcutPath(ShellUtil::ShortcutLocation location,
308 BrowserDistribution* dist,
310 base::FilePath* path);
312 // Updates shortcut in |location| (or creates it if |options| specify
313 // SHELL_SHORTCUT_CREATE_ALWAYS).
314 // |dist| gives the type of browser distribution currently in use.
315 // |properties| and |operation| affect this method as described on their
316 // invidividual definitions above.
317 // |location| may be one of SHORTCUT_LOCATION_DESKTOP,
318 // SHORTCUT_LOCATION_QUICK_LAUNCH, or SHORTCUT_LOCATION_START_MENU.
319 static bool CreateOrUpdateShortcut(
320 ShellUtil::ShortcutLocation location,
321 BrowserDistribution* dist,
322 const ShellUtil::ShortcutProperties& properties,
323 ShellUtil::ShortcutOperation operation);
325 // Returns the string "|icon_path|,|icon_index|" (see, for example,
326 // http://msdn.microsoft.com/library/windows/desktop/dd391573.aspx).
327 static string16 FormatIconLocation(const string16& icon_path, int icon_index);
329 // This method returns the command to open URLs/files using chrome. Typically
330 // this command is written to the registry under shell\open\command key.
331 // |chrome_exe|: the full path to chrome.exe
332 static string16 GetChromeShellOpenCmd(const string16& chrome_exe);
334 // This method returns the command to be called by the DelegateExecute verb
335 // handler to launch chrome on Windows 8. Typically this command is written to
336 // the registry under the HKCR\Chrome\.exe\shell\(open|run)\command key.
337 // |chrome_exe|: the full path to chrome.exe
338 static string16 GetChromeDelegateCommand(const string16& chrome_exe);
340 // Gets a mapping of all registered browser names (excluding browsers in the
341 // |dist| distribution) and their reinstall command (which usually sets
342 // browser as default).
343 // Given browsers can be registered in HKCU (as of Win7) and/or in HKLM, this
344 // method looks in both and gives precedence to values in HKCU as per the msdn
345 // standard: http://goo.gl/xjczJ.
346 static void GetRegisteredBrowsers(BrowserDistribution* dist,
347 std::map<string16, string16>* browsers);
349 // Returns the suffix this user's Chrome install is registered with.
350 // Always returns the empty string on system-level installs.
352 // This method is meant for external methods which need to know the suffix of
353 // the current install at run-time, not for install-time decisions.
354 // There are no guarantees that this suffix will not change later:
355 // (e.g. if two user-level installs were previously installed in parallel on
356 // the same machine, both without admin rights and with no user-level install
357 // having claimed the non-suffixed HKLM registrations, they both have no
358 // suffix in their progId entries (as per the old suffix rules). If they were
359 // to both fully register (i.e. click "Make Chrome Default" and go through
360 // UAC; or upgrade to Win8 and get the automatic no UAC full registration)
361 // they would then both get a suffixed registration as per the new suffix
364 // |chrome_exe| The path to the currently installed (or running) chrome.exe.
365 static string16 GetCurrentInstallationSuffix(BrowserDistribution* dist,
366 const string16& chrome_exe);
368 // Returns the application name of the program under |dist|.
369 // This application name will be suffixed as is appropriate for the current
371 // This is the name that is registered with Default Programs on Windows and
372 // that should thus be used to "make chrome default" and such.
373 static string16 GetApplicationName(BrowserDistribution* dist,
374 const string16& chrome_exe);
376 // Returns the AppUserModelId for |dist|. This identifier is unconditionally
377 // suffixed with a unique id for this user on user-level installs (in contrast
378 // to other registration entries which are suffixed as described in
379 // GetCurrentInstallationSuffix() above).
380 static string16 GetBrowserModelId(BrowserDistribution* dist,
381 bool is_per_user_install);
383 // Returns an AppUserModelId composed of each member of |components| separated
385 // The returned appid is guaranteed to be no longer than
386 // chrome::kMaxAppModelIdLength (some of the components might have been
387 // shortened to enforce this).
388 static string16 BuildAppModelId(const std::vector<string16>& components);
390 // Returns true if Chrome can make itself the default browser without relying
391 // on the Windows shell to prompt the user. This is the case for versions of
392 // Windows prior to Windows 8.
393 static bool CanMakeChromeDefaultUnattended();
395 // Returns the DefaultState of Chrome for HTTP and HTTPS.
396 static DefaultState GetChromeDefaultState();
398 // Returns the DefaultState of Chrome for |protocol|.
399 static DefaultState GetChromeDefaultProtocolClientState(
400 const string16& protocol);
402 // Make Chrome the default browser. This function works by going through
403 // the url protocols and file associations that are related to general
404 // browsing, e.g. http, https, .html etc., and requesting to become the
405 // default handler for each. If any of these fails the operation will return
406 // false to indicate failure, which is consistent with the return value of
407 // ShellIntegration::GetDefaultBrowser.
409 // In the case of failure any successful changes will be left, however no
410 // more changes will be attempted.
411 // TODO(benwells): Attempt to undo any changes that were successfully made.
412 // http://crbug.com/83970
414 // shell_change: Defined whether to register as default browser at system
415 // level or user level. If value has ShellChange::SYSTEM_LEVEL
416 // we should be running as admin user.
417 // chrome_exe: The chrome.exe path to register as default browser.
418 // elevate_if_not_admin: On Vista if user is not admin, try to elevate for
419 // Chrome registration.
420 static bool MakeChromeDefault(BrowserDistribution* dist,
422 const string16& chrome_exe,
423 bool elevate_if_not_admin);
425 // Shows and waits for the Windows 8 "How do you want to open webpages?"
426 // dialog if Chrome is not already the default HTTP/HTTPS handler. Also does
427 // XP-era registrations if Chrome is chosen or was already the default. Do
428 // not use on pre-Win8 OSes.
430 // |dist| gives the type of browser distribution currently in use.
431 // |chrome_exe| The chrome.exe path to register as default browser.
432 static bool ShowMakeChromeDefaultSystemUI(BrowserDistribution* dist,
433 const string16& chrome_exe);
435 // Make Chrome the default application for a protocol.
436 // chrome_exe: The chrome.exe path to register as default browser.
437 // protocol: The protocol to register as the default handler for.
438 static bool MakeChromeDefaultProtocolClient(BrowserDistribution* dist,
439 const string16& chrome_exe,
440 const string16& protocol);
442 // Shows and waits for the Windows 8 "How do you want to open links of this
443 // type?" dialog if Chrome is not already the default |protocol|
444 // handler. Also does XP-era registrations if Chrome is chosen or was already
445 // the default for |protocol|. Do not use on pre-Win8 OSes.
447 // |dist| gives the type of browser distribution currently in use.
448 // |chrome_exe| The chrome.exe path to register as default browser.
449 // |protocol| is the protocol being registered.
450 static bool ShowMakeChromeDefaultProtocolClientSystemUI(
451 BrowserDistribution* dist,
452 const string16& chrome_exe,
453 const string16& protocol);
455 // Registers Chrome as a potential default browser and handler for filetypes
457 // If Chrome is already registered, this method is a no-op.
458 // This method requires write access to HKLM (prior to Win8) so is just a
460 // If write to HKLM is required, but fails, and:
461 // - |elevate_if_not_admin| is true (and OS is Vista or above):
462 // tries to launch setup.exe with admin priviledges (by prompting the user
463 // with a UAC) to do these tasks.
464 // - |elevate_if_not_admin| is false (or OS is XP):
465 // adds the ProgId entries to HKCU. These entries will not make Chrome show
466 // in Default Programs but they are still useful because Chrome can be
467 // registered to run when the user clicks on an http link or an html file.
469 // |chrome_exe| full path to chrome.exe.
470 // |unique_suffix| Optional input. If given, this function appends the value
471 // to default browser entries names that it creates in the registry.
472 // Currently, this is only used to continue an install with the same suffix
473 // when elevating and calling setup.exe with admin privileges as described
475 // |elevate_if_not_admin| if true will make this method try alternate methods
476 // as described above. This should only be true when following a user action
477 // (e.g. "Make Chrome Default") as it allows this method to UAC.
479 // Returns true if Chrome is successfully registered (or already registered).
480 static bool RegisterChromeBrowser(BrowserDistribution* dist,
481 const string16& chrome_exe,
482 const string16& unique_suffix,
483 bool elevate_if_not_admin);
485 // This method declares to Windows that Chrome is capable of handling the
486 // given protocol. This function will call the RegisterChromeBrowser function
487 // to register with Windows as capable of handling the protocol, if it isn't
488 // currently registered as capable.
489 // Declaring the capability of handling a protocol is necessary to register
490 // as the default handler for the protocol in Vista and later versions of
493 // If called by the browser and elevation is required, it will elevate by
494 // calling setup.exe which will again call this function with elevate false.
496 // |chrome_exe| full path to chrome.exe.
497 // |unique_suffix| Optional input. If given, this function appends the value
498 // to default browser entries names that it creates in the registry.
499 // |protocol| The protocol to register as being capable of handling.s
500 // |elevate_if_not_admin| if true will make this method try alternate methods
501 // as described above.
502 static bool RegisterChromeForProtocol(BrowserDistribution* dist,
503 const string16& chrome_exe,
504 const string16& unique_suffix,
505 const string16& protocol,
506 bool elevate_if_not_admin);
508 // Removes installed shortcut(s) at |location|.
509 // |level|: CURRENT_USER to remove per-user shortcuts, or SYSTEM_LEVEL to
510 // remove all-users shortcuts.
511 // |target_exe|: Shortcut target exe; shortcuts will only be deleted when
512 // their target is |target_exe|.
513 // If |location| is SHORTCUT_LOCATION_START_MENU, the shortcut folder specific
514 // to |dist| is deleted.
515 // Returns true if all shortcuts pointing to |target_exe| are successfully
516 // deleted, including the case where no such shortcuts are found.
517 static bool RemoveShortcuts(ShellUtil::ShortcutLocation location,
518 BrowserDistribution* dist,
520 const base::FilePath& target_exe);
522 // Applies the updates in |properties| to all matching shortcuts in
524 // - the shortcut's original target is |target_exe|,
525 // - the original arguments are non-empty.
526 // Returns true if all updates to matching shortcuts are successful, including
527 // the vacuous case where no matching shortcuts are found.
528 static bool UpdateShortcutsWithArgs(
529 ShellUtil::ShortcutLocation location,
530 BrowserDistribution* dist,
532 const base::FilePath& target_exe,
533 const ShellUtil::ShortcutProperties& properties);
535 // Sets |suffix| to the base 32 encoding of the md5 hash of this user's sid
536 // preceded by a dot.
537 // This is guaranteed to be unique on the machine and 27 characters long
538 // (including the '.').
539 // This suffix is then meant to be added to all registration that may conflict
540 // with another user-level Chrome install.
541 // Note that prior to Chrome 21, the suffix registered used to be the user's
542 // username (see GetOldUserSpecificRegistrySuffix() below). We still honor old
543 // installs registered that way, but it was wrong because some of the
544 // characters allowed in a username are not allowed in a ProgId.
545 // Returns true unless the OS call to retrieve the username fails.
546 // NOTE: Only the installer should use this suffix directly. Other callers
547 // should call GetCurrentInstallationSuffix().
548 static bool GetUserSpecificRegistrySuffix(string16* suffix);
550 // Sets |suffix| to this user's username preceded by a dot. This suffix should
551 // only be used to support legacy installs that used this suffixing
553 // Returns true unless the OS call to retrieve the username fails.
554 // NOTE: Only the installer should use this suffix directly. Other callers
555 // should call GetCurrentInstallationSuffix().
556 static bool GetOldUserSpecificRegistrySuffix(string16* suffix);
558 // Returns the base32 encoding (using the [A-Z2-7] alphabet) of |bytes|.
559 // |size| is the length of |bytes|.
560 // Note: This method does not suffix the output with '=' signs as technically
561 // required by the base32 standard for inputs that aren't a multiple of 5
563 static string16 ByteArrayToBase32(const uint8* bytes, size_t size);
566 DISALLOW_COPY_AND_ASSIGN(ShellUtil);
570 #endif // CHROME_INSTALLER_UTIL_SHELL_UTIL_H_