Fix RegisterChromeBrowser definition and usage in shell_util

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_
@@ skipping 235 matching lines @@
   static bool ShowMakeChromeDefaultSystemUI(BrowserDistribution* dist,
                                             const string16& chrome_exe);
 
   // Make Chrome the default application for a protocol.
   // chrome_exe: The chrome.exe path to register as default browser.
   // protocol: The protocol to register as the default handler for.
   static bool MakeChromeDefaultProtocolClient(BrowserDistribution* dist,
                                               const string16& chrome_exe,
                                               const string16& protocol);
 
-  // This method adds Chrome to the list that shows up in Add/Remove Programs->
-  // Set Program Access and Defaults and also creates Chrome ProgIds under
-  // Software\Classes. This method requires write access to HKLM so is just
-  // best effort deal. If write to HKLM fails and elevate_if_not_admin is true,
-  // this method will:
-  // - add the ProgId entries to HKCU on XP. HKCU entries will not make
-  //   Chrome show in Set Program Access and Defaults but they are still useful
-  //   because we can make Chrome run when user clicks on http link or html
-  //   file.
-  // - will try to launch setup.exe with admin priviledges on Vista to do
-  //   these tasks. Users will see standard Vista elevation prompt and if they
-  //   enter the right credentials, the write operation will work.
-  // Currently elevate_if_not_admin is true only when user tries to make Chrome
-  // default browser (through the UI or through installer options) and Chrome
-  // is not registered on the machine.
+  // Registers Chrome as a potential default browser and handler for filetypes
+  // and protocols.
+  // If Chrome is already registered, this method is a no-op.
+  // This method requires write access to HKLM so is just a best effort deal.
+  // If write to HKLM fails and:
+  // - |elevate_if_not_admin| is true (and OS is Vista or above):
+  //   tries to launch setup.exe with admin priviledges (by prompting the user
+  //   with a UAC) to do these tasks.
+  // - |elevate_if_not_admin| is false (or OS is XP):
+  //   adds the ProgId entries to HKCU. These entries will not make Chrome show
+  //   in Default Programs but they are still useful because Chrome can be
+  //   registered to run when  the user clicks on an http link or an html file.

[grt (UTC plus 2), 2012/06/11 17:57:38]

nit: "when   the" -> "when the"

[gab, 2012/06/11 19:38:11]

Done.

   //
+  // |elevate_if_not_admin| should only be true when following a user action

[grt (UTC plus 2), 2012/06/11 17:57:38]

merge this in with the documentation for |elevate_if_not_admin| on line 277

[gab, 2012/06/11 19:38:11]

Ah good catch! Done.

+  // (e.g. "Make Chrome Default") as it allows this method to UAC.
   // |chrome_exe| full path to chrome.exe.
   // |unique_suffix| Optional input. If given, this function appends the value
   // to default browser entries names that it creates in the registry.
+  // Currently, this is only used to continue an install with the same suffix
+  // when elevating and calling setup.exe with admin privileges as described
+  // above.
   // |elevate_if_not_admin| if true will make this method try alternate methods
   // as described above.
+  //
+  // Returns true if Chrome is successfully registered (or already registered).
   static bool RegisterChromeBrowser(BrowserDistribution* dist,
                                     const string16& chrome_exe,
                                     const string16& unique_suffix,
                                     bool elevate_if_not_admin);
 
   // This method declares to Windows that Chrome is capable of handling the
   // given protocol. This function will call the RegisterChromeBrowser function
   // to register with Windows as capable of handling the protocol, if it isn't
   // currently registered as capable.
   // Declaring the capability of handling a protocol is necessary to register
@@ skipping 66 matching lines @@
                                    const string16& icon_path,
                                    int icon_index,
                                    uint32 options);
 
  private:
   DISALLOW_COPY_AND_ASSIGN(ShellUtil);
 };
 
 
 #endif  // CHROME_INSTALLER_UTIL_SHELL_UTIL_H_