[win] Change Chrome Watcher configuration API.

chrome/app/chrome_watcher_command_line_win.h

 // Copyright (c) 2014 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.
 
 #ifndef CHROME_APP_CHROME_WATCHER_COMMAND_LINE_WIN_H_
 #define CHROME_APP_CHROME_WATCHER_COMMAND_LINE_WIN_H_
 
 #include <windows.h>
 
+#include "base/command_line.h"
+#include "base/files/file_path.h"
 #include "base/win/scoped_handle.h"
 
-namespace base {
-class CommandLine;
-class FilePath;
-}  // namespace base
+// Class for configuring the Chrome watcher process via the command-line. This
+// accepts configuration from the parent process and generates the required
+// command-line.
+//
+// It provides functionality for the common task of sharing handles from a
+// parent to a child process, automatically duplicating them with the
+// appropriate permissions. These handles are closed when the generator is
+// destroyed so the generator must outlive the process creation.
+class ChromeWatcherCommandLineGenerator {
+ public:
+  explicit ChromeWatcherCommandLineGenerator(const base::FilePath& chrome_exe);
+
+  // Sets a handle to be shared with the child process. This will duplicate the
+  // handle with the inherit flag, with this object retaining ownership of the
+  // duplicated handle. As such, this object must live at least until after the
+  // watcher process has been created. Returns true on success, false on
+  // failure. This can fail if the call to DuplicateHandle fails. Each of this
+  // may only be called once.
+  bool SetOnInitializedEventHandle(HANDLE on_initialized_event_handle);
+  bool SetParentProcessHandle(HANDLE parent_process_handle_);
+
+  // Generates a command-line representing this configuration. Must be run from
+  // the main thread of the parent process.
+  base::CommandLine GenerateCommandLine();
+
+  // Appends all inherited handles to the provided vector. Does not clear the
+  // vector first.
+  void GetInheritedHandles(std::vector<HANDLE>* inherited_handles) const;

[grt (UTC plus 2), 2015/12/21 20:19:07]

#include <vector>

[chrisha, 2015/12/21 23:25:30]

Done.

+
+ protected:
+  // Exposed for unittesting.
+
+  // Duplicate the provided |handle|, making it inheritable, and storing it in
+  // the provided |scoped_handle|. Also updated inherited_handles_.
+  bool SetHandle(HANDLE handle, base::win::ScopedHandle* scoped_handle);
+
+  base::FilePath chrome_exe_;
+
+  // Duplicated inheritable handles that are being shared from the parent to the
+  // child.
+  base::win::ScopedHandle on_initialized_event_handle_;
+  base::win::ScopedHandle parent_process_handle_;
+
+ private:
+  DISALLOW_COPY_AND_ASSIGN(ChromeWatcherCommandLineGenerator);
+};
+
+// Class for processing a command-line used to start a Chrome Watcher process
+// and exposing the resulting configuration and any shared handles. To be used
+// within the watcher process.
+class ChromeWatcherCommandLineInterpreter {
+ public:
+  ChromeWatcherCommandLineInterpreter();
+
+  // Causes the process to explode if any inherited handles weren't collected
+  // via GetHandle.
+  ~ChromeWatcherCommandLineInterpreter();
+
+  // Parses the provided command-line used to launch a Chrome Watcher process.
+  // If this fails any successfully opened handles will be closed prior to
+  // return. Returns true on success, false otherwise.
+  bool InterpretCommandLine(const base::CommandLine& command_line);

[grt (UTC plus 2), 2015/12/21 20:19:07]

wdyt of:
class ChromeWatcherCommandLine {
 public:
  static scoped_ptr<ChromeWatcherCommandLine> Interpret(const base::CommandLine&
command_line);
...
};
then the getters don't need to be documented with "Only valid after..."
?

[chrisha, 2015/12/21 23:25:30]

Done.

+
+  // Retrieves a handle that has been inherited from a parent process. This can
+  // only be called once handle, and it is expected that all inherited handles
+  // are taken by the child process. Any handles left in this object will cause
+  // a terminal error at the time of object destruction.
+  bool TakeOnInitializedEventHandle(

[grt (UTC plus 2), 2015/12/21 20:19:07]

can these return the ScopedHandle (which appears to be a movable type)?

[chrisha, 2015/12/21 23:25:30]

Yup, they sure can.

Done.

+      base::win::ScopedHandle* on_initialized_event_handle);
+  bool TakeParentProcessHandle(base::win::ScopedHandle* parent_process_handle);
+
+  // Returns the ID of the main thread in the parent process. Only valid after
+  // a successful call to InterpretCommandLine.
+  DWORD main_thread_id() const { return main_thread_id_; }
+
+ private:
+  // Passes a handle from |internal_handle| to |external_handle|. Returns true
+  // on success, false if |internal_handle| was invalid.
+  bool TakeHandle(base::win::ScopedHandle* internal_handle,
+                  base::win::ScopedHandle* external_handle);
+
+  base::win::ScopedHandle on_initialized_event_handle_;
+  base::win::ScopedHandle parent_process_handle_;
+
+  // The ID of the main thread in the parent process.
+  DWORD main_thread_id_;
+
+  DISALLOW_COPY_AND_ASSIGN(ChromeWatcherCommandLineInterpreter);
+};
 
 // Generates a CommandLine that will launch |chrome_exe| in Chrome Watcher mode
 // to observe |parent_process|, whose main thread is identified by
 // |main_thread_id|. The watcher process will signal |on_initialized_event| when
 // its initialization is complete.
 base::CommandLine GenerateChromeWatcherCommandLine(
     const base::FilePath& chrome_exe,
     HANDLE parent_process,
     DWORD main_thread_id,
     HANDLE on_initialized_event);
 
 // Interprets the Command Line used to launch a Chrome Watcher process and
 // extracts the parent process and initialization event HANDLEs and the parent
 // process main thread ID. Verifies that the handles are usable in this process
 // before returning them. Returns true if all parameters are successfully parsed
 // and false otherwise. In case of partial failure, any successfully parsed
 // HANDLEs will be closed.
 bool InterpretChromeWatcherCommandLine(
     const base::CommandLine& command_line,
     base::win::ScopedHandle* parent_process,
     DWORD* main_thread_id,
     base::win::ScopedHandle* on_initialized_event);
 
 #endif  // CHROME_APP_CHROME_WATCHER_COMMAND_LINE_WIN_H_