Home | History | Annotate | Download | only in embedder 
      1 // Copyright 2014 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 #ifndef MOJO_EDK_EMBEDDER_PLATFORM_CHANNEL_PAIR_H_
      6 #define MOJO_EDK_EMBEDDER_PLATFORM_CHANNEL_PAIR_H_
      7 
      8 #include <memory>
      9 
     10 #include "base/macros.h"
     11 #include "base/process/launch.h"
     12 #include "build/build_config.h"
     13 #include "mojo/edk/embedder/scoped_platform_handle.h"
     14 #include "mojo/edk/system/system_impl_export.h"
     15 
     16 namespace base {
     17 class CommandLine;
     18 }
     19 
     20 namespace mojo {
     21 namespace edk {
     22 
     23 // It would be nice to refactor base/process/launch.h to have a more platform-
     24 // independent way of representing handles that are passed to child processes.
     25 #if defined(OS_WIN)
     26 using HandlePassingInformation = base::HandlesToInheritVector;
     27 #elif defined(OS_POSIX)
     28 using HandlePassingInformation = base::FileHandleMappingVector;
     29 #else
     30 #error "Unsupported."
     31 #endif
     32 
     33 // This is used to create a pair of |PlatformHandle|s that are connected by a
     34 // suitable (platform-specific) bidirectional "pipe" (e.g., socket on POSIX,
     35 // named pipe on Windows). The resulting handles can then be used in the same
     36 // process (e.g., in tests) or between processes. (The "server" handle is the
     37 // one that will be used in the process that created the pair, whereas the
     38 // "client" handle is the one that will be used in a different process.)
     39 //
     40 // This class provides facilities for passing the client handle to a child
     41 // process. The parent should call |PrepareToPassClientHandlelToChildProcess()|
     42 // to get the data needed to do this, spawn the child using that data, and then
     43 // call |ChildProcessLaunched()|. Note that on Windows this facility (will) only
     44 // work on Vista and later (TODO(vtl)).
     45 //
     46 // Note: |PlatformChannelPair()|, |PassClientHandleFromParentProcess()| and
     47 // |PrepareToPassClientHandleToChildProcess()| have platform-specific
     48 // implementations.
     49 //
     50 // Note: On POSIX platforms, to write to the "pipe", use
     51 // |PlatformChannel{Write,Writev}()| (from platform_channel_utils_posix.h)
     52 // instead of |write()|, |writev()|, etc. Otherwise, you have to worry about
     53 // platform differences in suppressing |SIGPIPE|.
     54 class MOJO_SYSTEM_IMPL_EXPORT PlatformChannelPair {
     55  public:
     56   static const char kMojoPlatformChannelHandleSwitch[];
     57 
     58   // If |client_is_blocking| is true, then the client handle only supports
     59   // blocking reads and writes. The default is nonblocking.
     60   PlatformChannelPair(bool client_is_blocking = false);
     61   ~PlatformChannelPair();
     62 
     63   ScopedPlatformHandle PassServerHandle();
     64 
     65   // For in-process use (e.g., in tests or to pass over another channel).
     66   ScopedPlatformHandle PassClientHandle();
     67 
     68   // To be called in the child process, after the parent process called
     69   // |PrepareToPassClientHandleToChildProcess()| and launched the child (using
     70   // the provided data), to create a client handle connected to the server
     71   // handle (in the parent process).
     72   static ScopedPlatformHandle PassClientHandleFromParentProcess(
     73       const base::CommandLine& command_line);
     74 
     75   // Like above, but gets the handle from the passed in string.
     76   static ScopedPlatformHandle PassClientHandleFromParentProcessFromString(
     77       const std::string& value);
     78 
     79   // Prepares to pass the client channel to a new child process, to be launched
     80   // using |LaunchProcess()| (from base/launch.h). Modifies |*command_line| and
     81   // |*handle_passing_info| as needed.
     82   // Note: For Windows, this method only works on Vista and later.
     83   void PrepareToPassClientHandleToChildProcess(
     84       base::CommandLine* command_line,
     85       HandlePassingInformation* handle_passing_info) const;
     86 
     87   // Like above, but returns a string instead of changing the command line.
     88   std::string PrepareToPassClientHandleToChildProcessAsString(
     89       HandlePassingInformation* handle_passing_info) const;
     90 
     91   // To be called once the child process has been successfully launched, to do
     92   // any cleanup necessary.
     93   void ChildProcessLaunched();
     94 
     95  private:
     96   ScopedPlatformHandle server_handle_;
     97   ScopedPlatformHandle client_handle_;
     98 
     99   DISALLOW_COPY_AND_ASSIGN(PlatformChannelPair);
    100 };
    101 
    102 }  // namespace edk
    103 }  // namespace mojo
    104 
    105 #endif  // MOJO_EDK_EMBEDDER_PLATFORM_CHANNEL_PAIR_H_
    106