Refactor ShellUtil shortcut code -- single multi-purpose methods as opposed to many slighlty diffe…

chrome/installer/util/shell_util.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 //
 // This file declares methods that are useful for integrating Chrome in
 // Windows shell. These methods are all static and currently part of
 // ShellUtil class.
 
 #ifndef CHROME_INSTALLER_UTIL_SHELL_UTIL_H_
 #define CHROME_INSTALLER_UTIL_SHELL_UTIL_H_
 
 #include <windows.h>
 
 #include <map>
 #include <vector>
 
 #include "base/basictypes.h"
+#include "base/file_path.h"
 #include "base/string16.h"
 #include "chrome/installer/util/work_item_list.h"
 
 class BrowserDistribution;
-class FilePath;
-
-namespace base {
-class DictionaryValue;
-}
 
 // This is a utility class that provides common shell integration methods
 // that can be used by installer as well as Chrome.
 class ShellUtil {
  public:
   // Input to any methods that make changes to OS shell.
   enum ShellChange {
     CURRENT_USER = 0x1,  // Make any shell changes only at the user level
     SYSTEM_LEVEL = 0x2   // Make any shell changes only at the system level
   };
 
-  enum VerifyShortcutStatus {
-    VERIFY_SHORTCUT_SUCCESS = 0,
-    VERIFY_SHORTCUT_FAILURE_UNEXPECTED,
-    VERIFY_SHORTCUT_FAILURE_PATH,
-    VERIFY_SHORTCUT_FAILURE_DESCRIPTION,
-    VERIFY_SHORTCUT_FAILURE_ICON_INDEX,
+  // Typical shortcut directories. Resolved in GetShortcutPath().
+  enum ChromeShortcutLocation {
+    SHORTCUT_DESKTOP,
+    SHORTCUT_QUICK_LAUNCH,
+    SHORTCUT_START_MENU,
+  };
+
+  enum ChromeShortcutOperation {
+    // Create a new shortcut (overwriting if necessary).
+    SHORTCUT_CREATE_ALWAYS,
+    // Create the per-user shortcut only if its system-level equivalent is not
+    // present.
+    SHORTCUT_CREATE_IF_NO_SYSTEM_LEVEL,
+    // Overwrite an existing shortcut (fail if the shortcut doesn't exist).
+    SHORTCUT_REPLACE_EXISTING,
+    // Update specified properties only on an existing shortcut.
+    SHORTCUT_UPDATE_EXISTING,
+  };
+
+  // Properties for shortcuts to chrome.exe. Properties set will be applied to
+  // the shortcut on creation/update. On update, unset properties are ignored;
+  // on create unset properties might have a default value (see individual
+  // property setters below for details).
+  // Callers are encouraged to use the setters provided which take care of
+  // setting |options| as desired.
+  struct ChromeShortcutProperties {
+    enum ChromeIndividualProperties {
+      PROPERTIES_CHROME_EXE = 1 << 0,
+      PROPERTIES_ARGUMENTS = 1 << 1,
+      PROPERTIES_DESCRIPTION = 1 << 2,
+      PROPERTIES_ICON = 1 << 3,
+      PROPERTIES_APP_ID = 1 << 4,
+      PROPERTIES_SHORTCUT_NAME = 1 << 5,
+      PROPERTIES_DUAL_MODE = 1 << 6,
+    };
+
+    explicit ChromeShortcutProperties(ShellChange level_in)
+        : level(level_in), dual_mode(false), pin_to_taskbar(false),
+          options(0U) {}
+
+    // Sets the chrome.exe to launch from this shortcut. This is mandatory when
+    // creating a shortcut.
+    void set_chrome_exe(const FilePath& chrome_exe_in) {
+      chrome_exe = chrome_exe_in;
+      options |= PROPERTIES_CHROME_EXE;
+    }
+
+    // Sets the arguments to be passed to |chrome_exe| when launching from this
+    // shortcut.
+    // The length of this string must be less than MAX_PATH.
+    void set_arguments(const string16& arguments_in) {
+      arguments = arguments_in;
+      options |= PROPERTIES_ARGUMENTS;
+    }
+
+    // Sets the localized description of the shortcut.
+    // Default for chrome.exe: the current distribution's description.

[robertshield, 2012/10/04 00:25:23]

Isn't this in fact the default for SHORTCUT_CREATE_ALWAYS or
SHORTCUT_REPLACE_EXISTING?

[gab, 2012/10/04 04:10:32]

Whoops forgot "for chrome.exe" on this one, removed.

Clarified comment at the top of the struct about defaults to say this is also
true on replace.

+    // The length of this string must be less than MAX_PATH.

[robertshield, 2012/10/04 00:25:23]

Where is this MAX_PATH restriction enforced? Should it be DCHECKed here?

[gab, 2012/10/04 04:10:32]

MAX_PATH is enforced in base::win::shortcut.h, I brought the comment here
because I felt it wasn't right for the caller to have to read the underlying
interface, I guess I should also bring the DCHECK to avoid someone having the
same question later (and to make sure we catch dev-errors asap).

Done.

+    void set_description(const string16& description_in) {
+      description = description_in;
+      options |= PROPERTIES_DESCRIPTION;
+    }
+
+    // Sets the path to the icon (icon_index set to 0).
+    // Default: chrome.exe (icon_index defaults to the current distribution's
+    // icon index unless otherwise specified in master_preferences).
+    void set_icon(const FilePath& icon_in) {
+      icon = icon_in;
+      options |= PROPERTIES_ICON;
+    }
+
+    // Sets the app model id for the shortcut (Win7+).
+    // Default: the browser model id for the current install.
+    void set_app_id(const string16& app_id_in) {
+      app_id = app_id_in;
+      options |= PROPERTIES_APP_ID;
+    }
+
+    // Forces the shortcut's name to |shortcut_name_in|.
+    // Default: the current distribution's GetAppShortcutName().
+    // The ".lnk" extension will automatically be added to this name.
+    void set_shortcut_name(const string16& shortcut_name_in) {
+      shortcut_name = shortcut_name_in;
+      options |= PROPERTIES_SHORTCUT_NAME;
+    }
+
+    // Sets whether this is a dual mode shortcut (Win8+).
+    void set_dual_mode(bool dual_mode_in) {
+      dual_mode = dual_mode_in;
+      options |= PROPERTIES_DUAL_MODE;
+    }
+
+    // Sets whether to pin this shortcut to the taskbar after creating it
+    // (ignored if the shortcut is only being updated).
+    // Note: This property doesn't have a mask in |options|.
+    void set_pin_to_taskbar(bool pin_to_taskbar_in) {
+      pin_to_taskbar = pin_to_taskbar_in;
+    }
+
+    // The level to install this shortcut at (CURRENT_USER for a per-user
+    // shortcut and SYSTEM_LEVEL for an all-users shortcut).
+    ShellChange level;
+
+    FilePath chrome_exe;
+    string16 arguments;
+    string16 description;
+    FilePath icon;
+    string16 app_id;
+    string16 shortcut_name;
+    bool dual_mode;
+    bool pin_to_taskbar;
+    // Bitfield made of IndividualProperties. Properties set in |options| will
+    // be used to create/update the shortcut, others will be ignored on update
+    // and possibly replaced by default values on create (see individual
+    // property setters above for details on default values).
+    uint32 options;
   };
 
   // Relative path of the URL Protocol registry entry (prefixed with '\').
   static const wchar_t* kRegURLProtocol;
 
   // Relative path of DefaultIcon registry entry (prefixed with '\').
   static const wchar_t* kRegDefaultIcon;
 
   // Relative path of "shell" registry key.
   static const wchar_t* kRegShellPath;
@@ skipping 81 matching lines @@
   // Registry value name for the OpenWithProgids entry for file associations.
   static const wchar_t* kRegOpenWithProgids;
 
   // Returns true if |chrome_exe| is registered in HKLM with |suffix|.
   // Note: This only checks one deterministic key in HKLM for |chrome_exe| and
   // doesn't otherwise validate a full Chrome install in HKLM.
   static bool QuickIsChromeRegisteredInHKLM(BrowserDistribution* dist,
                                             const string16& chrome_exe,
                                             const string16& suffix);
 
-  // Creates Chrome shortcut on the Desktop.
+  // Sets |path| to the path for a shortcut at the |location| desired for the
+  // given |level| (CURRENT_USER for per-user path and SYSTEM_LEVEL for
+  // all-users path).
+  // Returns false on failure.
+  static bool GetShortcutPath(ChromeShortcutLocation location,
+                              BrowserDistribution* dist,
+                              ShellChange level,
+                              FilePath* path);
+
+  // Updates Chrome shortcut in |location| (or creates it if |options| specify
+  // SHORTCUT_CREATE_ALWAYS).
   // |dist| gives the type of browser distribution currently in use.
-  // |chrome_exe| provides the target path information.
-  // |description| provides the shortcut's "comment" property.
-  // |appended_name| provides a string to be appended to the distribution name,
-  //     and can be the empty string.
-  // |arguments| gives a set of arguments to be passed to the executable.
-  // |icon_path| provides the path to the icon file to use.
-  // |icon_index| provides the index of the icon within the provided icon file.
-  // If |shell_change| is CURRENT_USER, the shortcut is created in the
-  //     Desktop folder of current user's profile.
-  // If |shell_change| is SYSTEM_LEVEL, the shortcut is created in the
-  //     Desktop folder of the "All Users" profile.
-  // |options|: bitfield for which the options come from ChromeShortcutOptions.
-  // Returns true iff the method causes a shortcut to be created / updated.
-  static bool CreateChromeDesktopShortcut(BrowserDistribution* dist,
-                                          const string16& chrome_exe,
-                                          const string16& description,
-                                          const string16& appended_name,
-                                          const string16& arguments,
-                                          const string16& icon_path,
-                                          int icon_index,
-                                          ShellChange shell_change,
-                                          uint32 options);
-
-  // Create Chrome shortcut on Quick Launch Bar.
-  // If shell_change is CURRENT_USER, the shortcut is created in the
-  // Quick Launch folder of current user's profile.
-  // If shell_change is SYSTEM_LEVEL, the shortcut is created in the
-  // Quick Launch folder of "Default User" profile. This will make sure
-  // that this shortcut will be seen by all the new users logging into the
-  // system.
-  // |options|: bitfield for which the options come from ChromeShortcutOptions.
-  static bool CreateChromeQuickLaunchShortcut(BrowserDistribution* dist,
-                                              const string16& chrome_exe,
-                                              int shell_change,
-                                              uint32 options);
+  // |properties| and |operation| affect this method as described on their
+  // invidividual definitions above.
+  static bool CreateOrUpdateChromeShortcut(
+      ChromeShortcutLocation location,
+      BrowserDistribution* dist,
+      const ChromeShortcutProperties& properties,
+      ChromeShortcutOperation operation);
 
   // This method appends the Chrome icon index inside chrome.exe to the
   // chrome.exe path passed in as input, to generate the full path for
   // Chrome icon that can be used as value for Windows registry keys.
   // |chrome_exe| full path to chrome.exe.
   static string16 GetChromeIcon(BrowserDistribution* dist,
                                 const string16& chrome_exe);
 
   // This method returns the command to open URLs/files using chrome. Typically
   // this command is written to the registry under shell\open\command key.
   // |chrome_exe|: the full path to chrome.exe
   static string16 GetChromeShellOpenCmd(const string16& chrome_exe);
 
   // This method returns the command to be called by the DelegateExecute verb
   // handler to launch chrome on Windows 8. Typically this command is written to
   // the registry under the HKCR\Chrome\.exe\shell\(open|run)\command key.
   // |chrome_exe|: the full path to chrome.exe
   static string16 GetChromeDelegateCommand(const string16& chrome_exe);
 
-  // Returns the localized name of Chrome shortcut in |shortcut|. If
-  // |appended_name| is not empty, it is included in the shortcut name. If
-  // |alternate| is true, a second localized text that is better suited for
-  // certain scenarios is used.
-  static bool GetChromeShortcutName(BrowserDistribution* dist,
-                                    bool alternate,
-                                    const string16& appended_name,
-                                    string16* shortcut);
-
-  // Gets the desktop path for the current user or all users (if system_level
-  // is true) and returns it in 'path' argument. Return true if successful,
-  // otherwise returns false.
-  static bool GetDesktopPath(bool system_level, FilePath* path);
-
-  // Gets the Quick Launch shortcuts path for the current user and
-  // returns it in 'path' argument. Return true if successful, otherwise
-  // returns false. If system_level is true this function returns the path
-  // to Default Users Quick Launch shortcuts path. Adding a shortcut to Default
-  // User's profile only affects any new user profiles (not existing ones).
-  static bool GetQuickLaunchPath(bool system_level, FilePath* path);
-
   // Gets a mapping of all registered browser names (excluding browsers in the
   // |dist| distribution) and their reinstall command (which usually sets
   // browser as default).
   // Given browsers can be registered in HKCU (as of Win7) and/or in HKLM, this
   // method looks in both and gives precedence to values in HKCU as per the msdn
   // standard: http://goo.gl/xjczJ.
   static void GetRegisteredBrowsers(BrowserDistribution* dist,
                                     std::map<string16, string16>* browsers);
 
   // Returns the suffix this user's Chrome install is registered with.
@@ skipping 139 matching lines @@
   // to default browser entries names that it creates in the registry.
   // |protocol| The protocol to register as being capable of handling.s
   // |elevate_if_not_admin| if true will make this method try alternate methods
   // as described above.
   static bool RegisterChromeForProtocol(BrowserDistribution* dist,
                                         const string16& chrome_exe,
                                         const string16& unique_suffix,
                                         const string16& protocol,
                                         bool elevate_if_not_admin);
 
-  // Remove Chrome shortcut from Desktop.
-  // If |shell_change| is CURRENT_USER, the shortcut is removed from the
-  // Desktop folder of current user's profile.
-  // If |shell_change| is SYSTEM_LEVEL, the shortcut is removed from the
-  // Desktop folder of "All Users" profile.
-  // |options|: bitfield for which the options come from ChromeShortcutOptions.
-  // Only SHORTCUT_ALTERNATE is a valid option for this function.
-  static bool RemoveChromeDesktopShortcut(BrowserDistribution* dist,
-                                          int shell_change,
-                                          uint32 options);
-
-  // Removes a set of existing Chrome desktop shortcuts. |appended_names| is a
-  // list of shortcut file names as obtained from
-  // ShellUtil::GetChromeShortcutName.
-  static bool RemoveChromeDesktopShortcutsWithAppendedNames(
-      const std::vector<string16>& appended_names);
-
-  // Remove Chrome shortcut from Quick Launch Bar.
-  // If shell_change is CURRENT_USER, the shortcut is removed from
-  // the Quick Launch folder of current user's profile.
-  // If shell_change is SYSTEM_LEVEL, the shortcut is removed from
-  // the Quick Launch folder of "Default User" profile.
-  static bool RemoveChromeQuickLaunchShortcut(BrowserDistribution* dist,
-                                              int shell_change);
+  // Removes installed Chrome shortcut at |location|.
+  // |level|: CURRENT_USER to remove the per-user shortcut and SYSTEM_LEVEL to
+  // remove the all-users shortcut.
+  // |shortcut_name|: If non-null, remove the shortcut named |shortcut_name| at
+  // location; otherwise remove the default shortcut at |location|.
+  // If |location| is SHORTCUT_START_MENU the shortcut folder specific to |dist|
+  // is deleted.
+  // Also attempts to unpin the removed shortcut from the taskbar.
+  // Returns true unless an unexpected failure occurs (i.e. returns true even if
+  // no shortcut is found at |location|).

[robertshield, 2012/10/04 00:25:23]

For this last sentence, how about:
"Returns true on success or if no shortcut is found at |location|."

[gab, 2012/10/04 04:10:32]

Sure.

+  static bool RemoveChromeShortcut(ChromeShortcutLocation location,
+                                   BrowserDistribution* dist,
+                                   ShellChange level,
+                                   const string16* shortcut_name);
 
   // This will remove all secondary tiles from the start screen for |dist|.
   static void RemoveChromeStartScreenShortcuts(BrowserDistribution* dist,
                                                const string16& chrome_exe);
 
-  enum ChromeShortcutOptions {
-    SHORTCUT_NO_OPTIONS = 0,
-    // Set DualMode property for Windows 8 Metro-enabled shortcuts.
-    SHORTCUT_DUAL_MODE = 1 << 0,
-    // Create a new shortcut (overwriting if necessary).
-    SHORTCUT_CREATE_ALWAYS = 1 << 1,
-    // Use an alternate application name for the shortcut (e.g. "The Internet").
-    // This option is only applied to the Desktop shortcut.
-    SHORTCUT_ALTERNATE = 1 << 2,
-  };
-
-  // Updates shortcut (or creates a new shortcut) at destination given by
-  // shortcut to a target given by chrome_exe. The arguments are given by
-  // |arguments| for the target and icon is set based on |icon_path| and
-  // |icon_index|. If create_new is set to true, the function will create a new
-  // shortcut if it doesn't exist.
-  // |options|: bitfield for which the options come from ChromeShortcutOptions.
-  // If SHORTCUT_CREATE_ALWAYS is not set in |options|, only specified (non-
-  // null) properties on an existing shortcut will be modified. If the shortcut
-  // does not exist, this method is a no-op and returns false.
-  static bool UpdateChromeShortcut(BrowserDistribution* dist,
-                                   const string16& chrome_exe,
-                                   const string16& shortcut,
-                                   const string16& arguments,
-                                   const string16& description,
-                                   const string16& icon_path,
-                                   int icon_index,
-                                   uint32 options);
-
   // Sets |suffix| to the base 32 encoding of the md5 hash of this user's sid
   // preceded by a dot.
   // This is guaranteed to be unique on the machine and 27 characters long
   // (including the '.').
   // This suffix is then meant to be added to all registration that may conflict
   // with another user-level Chrome install.
   // Note that prior to Chrome 21, the suffix registered used to be the user's
   // username (see GetOldUserSpecificRegistrySuffix() below). We still honor old
   // installs registered that way, but it was wrong because some of the
   // characters allowed in a username are not allowed in a ProgId.
@@ skipping 16 matching lines @@
   // required by the base32 standard for inputs that aren't a multiple of 5
   // bytes.
   static string16 ByteArrayToBase32(const uint8* bytes, size_t size);
 
  private:
   DISALLOW_COPY_AND_ASSIGN(ShellUtil);
 };
 
 
 #endif  // CHROME_INSTALLER_UTIL_SHELL_UTIL_H_