1 // Copyright 2018 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_PUBLIC_CPP_PLATFORM_PLATFORM_CHANNEL_H_ 6 #define MOJO_PUBLIC_CPP_PLATFORM_PLATFORM_CHANNEL_H_ 7 8 #include "base/command_line.h" 9 #include "base/component_export.h" 10 #include "base/macros.h" 11 #include "base/process/launch.h" 12 #include "build/build_config.h" 13 #include "mojo/public/cpp/platform/platform_channel_endpoint.h" 14 15 namespace mojo { 16 17 // PlatformChannel encapsulates construction and ownership of two entangled 18 // endpoints of a platform-specific communication primitive, e.g. a Windows pipe 19 // or a Unix domain socket. One endpoint is designated as the "local" endpoint 20 // and should be retained by the creating process; the other endpoint is 21 // designated as the "remote" endpoint and should be passed to an external 22 // process. 23 // 24 // PlatformChannels can be used to bootstrap Mojo IPC between one process and 25 // another. Typically the other process is a child of this process, and there 26 // are helper methods for passing the endpoint to a child as such; but this 27 // arrangement is not strictly necessary on all platforms. 28 // 29 // For a channel which allows clients to connect by name (i.e. a named pipe 30 // or socket server, supported only on Windows and POSIX systems) see 31 // NamedPlatformChannel. COMPONENT_EXPORT(MOJO_CPP_PLATFORM)32class COMPONENT_EXPORT(MOJO_CPP_PLATFORM) PlatformChannel { 33 public: 34 // A common helper constant that is used to pass handle values on the 35 // command line when the relevant methods are used on this class. 36 static const char kHandleSwitch[]; 37 38 // Unfortunately base process support code has no unified handle-passing 39 // data pipe, so we have this. 40 #if defined(OS_WIN) 41 using HandlePassingInfo = base::HandlesToInheritVector; 42 #elif defined(OS_FUCHSIA) 43 using HandlePassingInfo = base::HandlesToTransferVector; 44 #elif defined(OS_POSIX) 45 using HandlePassingInfo = base::FileHandleMappingVector; 46 #else 47 #error "Unsupported platform." 48 #endif 49 50 PlatformChannel(); 51 PlatformChannel(PlatformChannel&& other); 52 ~PlatformChannel(); 53 54 PlatformChannel& operator=(PlatformChannel&& other); 55 56 const PlatformChannelEndpoint& local_endpoint() const { 57 return local_endpoint_; 58 } 59 const PlatformChannelEndpoint& remote_endpoint() const { 60 return remote_endpoint_; 61 } 62 63 PlatformChannelEndpoint TakeLocalEndpoint() WARN_UNUSED_RESULT { 64 return std::move(local_endpoint_); 65 } 66 67 PlatformChannelEndpoint TakeRemoteEndpoint() WARN_UNUSED_RESULT { 68 return std::move(remote_endpoint_); 69 } 70 71 // Prepares to pass the remote endpoint handle to a process that will soon be 72 // launched. Returns a string that can be used in the remote process with 73 // |RecoverPassedEndpointFromString()| (see below). The string can e.g. be 74 // passed on the new process's command line. 75 // 76 // **NOTE**: If this method is called it is important to also call 77 // |RemoteProcessLaunchAttempted()| on this PlatformChannel *after* attempting 78 // to launch the new process, regardless of whether the attempt succeeded. 79 // Failing to do so can result in leaked handles. 80 void PrepareToPassRemoteEndpoint(HandlePassingInfo* info, std::string* value); 81 82 // Like above but modifies |*command_line| to include the endpoint string 83 // via the |kHandleSwitch| flag. 84 void PrepareToPassRemoteEndpoint(HandlePassingInfo* info, 85 base::CommandLine* command_line); 86 87 // Like above but adds handle-passing information directly to 88 // |*launch_options|, eliminating the potential need for callers to write 89 // platform-specific code to do the same. 90 void PrepareToPassRemoteEndpoint(base::LaunchOptions* options, 91 base::CommandLine* command_line); 92 93 // Must be called after the corresponding process launch attempt if 94 // |PrepareToPassRemoteEndpoint()| was used. 95 void RemoteProcessLaunchAttempted(); 96 97 // Recovers an endpoint handle which was passed to the calling process by 98 // its creator. |value| is a string returned by 99 // |PrepareToPassRemoteEndpoint()| in the creator's process. 100 static PlatformChannelEndpoint RecoverPassedEndpointFromString( 101 base::StringPiece value) WARN_UNUSED_RESULT; 102 103 // Like above but extracts the input string from |command_line| via the 104 // |kHandleSwitch| flag. 105 static PlatformChannelEndpoint RecoverPassedEndpointFromCommandLine( 106 const base::CommandLine& command_line) WARN_UNUSED_RESULT; 107 108 private: 109 PlatformChannelEndpoint local_endpoint_; 110 PlatformChannelEndpoint remote_endpoint_; 111 112 DISALLOW_COPY_AND_ASSIGN(PlatformChannel); 113 }; 114 115 } // namespace mojo 116 117 #endif // MOJO_PUBLIC_CPP_PLATFORM_PLATFORM_CHANNEL_H_ 118