shell_util.h revision d0247b1b59f9c528cb6df88b4f2b9afaf80d181e
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. 4// 5// This file declares methods that are useful for integrating Chrome in 6// Windows shell. These methods are all static and currently part of 7// ShellUtil class. 8 9#ifndef CHROME_INSTALLER_UTIL_SHELL_UTIL_H_ 10#define CHROME_INSTALLER_UTIL_SHELL_UTIL_H_ 11 12#include <windows.h> 13 14#include <map> 15#include <vector> 16 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" 22 23class BrowserDistribution; 24 25// This is a utility class that provides common shell integration methods 26// that can be used by installer as well as Chrome. 27class ShellUtil { 28 public: 29 // Input to any methods that make changes to OS shell. 30 enum ShellChange { 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 33 }; 34 35 // Chrome's default handler state for a given protocol. 36 enum DefaultState { 37 UNKNOWN_DEFAULT, 38 NOT_DEFAULT, 39 IS_DEFAULT, 40 }; 41 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 + 50 }; 51 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, 64 }; 65 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, 81 }; 82 83 explicit ShortcutProperties(ShellChange level_in) 84 : level(level_in), icon_index(0), dual_mode(false), 85 pin_to_taskbar(false), options(0U) {} 86 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) { 90 target = target_in; 91 options |= PROPERTIES_TARGET; 92 } 93 94 // Sets the arguments to be passed to |target| when launching from this 95 // shortcut. 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; 103 } 104 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; 113 } 114 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) { 118 icon = icon_in; 119 icon_index = icon_index_in; 120 options |= PROPERTIES_ICON; 121 } 122 123 // Sets the app model id for the shortcut (Win7+). 124 void set_app_id(const string16& app_id_in) { 125 app_id = app_id_in; 126 options |= PROPERTIES_APP_ID; 127 } 128 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; 135 } 136 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 140 // mode. 141 void set_dual_mode(bool dual_mode_in) { 142 dual_mode = dual_mode_in; 143 options |= PROPERTIES_DUAL_MODE; 144 } 145 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; 151 } 152 153 bool has_target() const { 154 return (options & PROPERTIES_TARGET) != 0; 155 } 156 157 bool has_arguments() const { 158 return (options & PROPERTIES_ARGUMENTS) != 0; 159 } 160 161 bool has_description() const { 162 return (options & PROPERTIES_DESCRIPTION) != 0; 163 } 164 165 bool has_icon() const { 166 return (options & PROPERTIES_ICON) != 0; 167 } 168 169 bool has_app_id() const { 170 return (options & PROPERTIES_APP_ID) != 0; 171 } 172 173 bool has_shortcut_name() const { 174 return (options & PROPERTIES_SHORTCUT_NAME) != 0; 175 } 176 177 bool has_dual_mode() const { 178 return (options & PROPERTIES_DUAL_MODE) != 0; 179 } 180 181 // The level to install this shortcut at (CURRENT_USER for a per-user 182 // shortcut and SYSTEM_LEVEL for an all-users shortcut). 183 ShellChange level; 184 185 base::FilePath target; 186 string16 arguments; 187 string16 description; 188 base::FilePath icon; 189 int icon_index; 190 string16 app_id; 191 string16 shortcut_name; 192 bool dual_mode; 193 bool pin_to_taskbar; 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). 198 uint32 options; 199 }; 200 201 // Relative path of the URL Protocol registry entry (prefixed with '\'). 202 static const wchar_t* kRegURLProtocol; 203 204 // Relative path of DefaultIcon registry entry (prefixed with '\'). 205 static const wchar_t* kRegDefaultIcon; 206 207 // Relative path of "shell" registry key. 208 static const wchar_t* kRegShellPath; 209 210 // Relative path of shell open command in Windows registry 211 // (i.e. \\shell\\open\\command). 212 static const wchar_t* kRegShellOpen; 213 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; 217 218 // Relative path of Classes registry entry under which file associations 219 // are added on Windows. 220 static const wchar_t* kRegClasses; 221 222 // Relative path of RegisteredApplications registry entry under which 223 // we add Chrome as a Windows application 224 static const wchar_t* kRegRegisteredApplications; 225 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; 230 231 // Registry path that stores url associations on Vista. 232 static const wchar_t* kRegVistaUrlPrefs; 233 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[]; 237 238 // File extensions that Chrome registers itself as being capable of 239 // handling. 240 static const wchar_t* kPotentialFileAssociations[]; 241 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[]; 245 246 // Protocols that Chrome registers itself as being capable of handling. 247 static const wchar_t* kPotentialProtocolAssociations[]; 248 249 // Registry value name that is needed for ChromeHTML ProgId 250 static const wchar_t* kRegUrlProtocol; 251 252 // Relative registry path from \Software\Classes\ChromeHTML to the ProgId 253 // Application definitions. 254 static const wchar_t* kRegApplication; 255 256 // Registry value name for the AppUserModelId of an application. 257 static const wchar_t* kRegAppUserModelId; 258 259 // Registry value name for the description of an application. 260 static const wchar_t* kRegApplicationDescription; 261 262 // Registry value name for an application's name. 263 static const wchar_t* kRegApplicationName; 264 265 // Registry value name for the path to an application's icon. 266 static const wchar_t* kRegApplicationIcon; 267 268 // Registry value name for an application's company. 269 static const wchar_t* kRegApplicationCompany; 270 271 // Relative path of ".exe" registry key. 272 static const wchar_t* kRegExePath; 273 274 // Registry value name of the open verb. 275 static const wchar_t* kRegVerbOpen; 276 277 // Registry value name of the opennewwindow verb. 278 static const wchar_t* kRegVerbOpenNewWindow; 279 280 // Registry value name of the run verb. 281 static const wchar_t* kRegVerbRun; 282 283 // Registry value name for command entries. 284 static const wchar_t* kRegCommand; 285 286 // Registry value name for the DelegateExecute verb handler. 287 static const wchar_t* kRegDelegateExecute; 288 289 // Registry value name for the OpenWithProgids entry for file associations. 290 static const wchar_t* kRegOpenWithProgids; 291 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); 298 299 // Returns true if the current Windows version supports the presence of 300 // shortcuts at |location|. 301 static bool ShortcutLocationIsSupported(ShellUtil::ShortcutLocation location); 302 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 305 // all-users path). 306 // Returns false on failure. 307 static bool GetShortcutPath(ShellUtil::ShortcutLocation location, 308 BrowserDistribution* dist, 309 ShellChange level, 310 base::FilePath* path); 311 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); 324 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); 328 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); 333 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); 339 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); 348 349 // Returns the suffix this user's Chrome install is registered with. 350 // Always returns the empty string on system-level installs. 351 // 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 362 // rules). 363 // 364 // |chrome_exe| The path to the currently installed (or running) chrome.exe. 365 static string16 GetCurrentInstallationSuffix(BrowserDistribution* dist, 366 const string16& chrome_exe); 367 368 // Returns the application name of the program under |dist|. 369 // This application name will be suffixed as is appropriate for the current 370 // install. 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); 375 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); 382 383 // Returns an AppUserModelId composed of each member of |components| separated 384 // by dots. 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); 389 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(); 394 395 // Returns the DefaultState of Chrome for HTTP and HTTPS. 396 static DefaultState GetChromeDefaultState(); 397 398 // Returns the DefaultState of Chrome for |protocol|. 399 static DefaultState GetChromeDefaultProtocolClientState( 400 const string16& protocol); 401 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. 408 // 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 413 // 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, 421 int shell_change, 422 const string16& chrome_exe, 423 bool elevate_if_not_admin); 424 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. 429 // 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); 434 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); 441 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. 446 // 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); 454 455 // Registers Chrome as a potential default browser and handler for filetypes 456 // and protocols. 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 459 // best effort deal. 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. 468 // 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 474 // above. 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. 478 // 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); 484 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 491 // Windows. 492 // 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. 495 // 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); 507 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, 519 ShellChange level, 520 const base::FilePath& target_exe); 521 522 // Applies the updates in |properties| to all matching shortcuts in 523 // |location|, i.e.: 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, 531 ShellChange level, 532 const base::FilePath& target_exe, 533 const ShellUtil::ShortcutProperties& properties); 534 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); 549 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 552 // style. 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); 557 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 562 // bytes. 563 static string16 ByteArrayToBase32(const uint8* bytes, size_t size); 564 565 private: 566 DISALLOW_COPY_AND_ASSIGN(ShellUtil); 567}; 568 569 570#endif // CHROME_INSTALLER_UTIL_SHELL_UTIL_H_ 571