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_EMBEDDER_H_ 6 #define MOJO_EDK_EMBEDDER_EMBEDDER_H_ 7 8 #include <stddef.h> 9 10 #include <memory> 11 #include <string> 12 13 #include "base/callback.h" 14 #include "base/command_line.h" 15 #include "base/memory/ref_counted.h" 16 #include "base/memory/shared_memory_handle.h" 17 #include "base/process/process_handle.h" 18 #include "base/task_runner.h" 19 #include "mojo/edk/embedder/scoped_platform_handle.h" 20 #include "mojo/edk/system/system_impl_export.h" 21 #include "mojo/public/cpp/system/message_pipe.h" 22 23 namespace base { 24 class PortProvider; 25 } 26 27 namespace mojo { 28 namespace edk { 29 30 class ProcessDelegate; 31 32 using ProcessErrorCallback = base::Callback<void(const std::string& error)>; 33 34 // Basic configuration/initialization ------------------------------------------ 35 36 // |Init()| sets up the basic Mojo system environment, making the |Mojo...()| 37 // functions available and functional. This is never shut down (except in tests 38 // -- see test_embedder.h). 39 40 // Allows changing the default max message size. Must be called before Init. 41 MOJO_SYSTEM_IMPL_EXPORT void SetMaxMessageSize(size_t bytes); 42 43 // Called in the parent process for each child process that is launched. 44 MOJO_SYSTEM_IMPL_EXPORT void ChildProcessLaunched( 45 base::ProcessHandle child_process, 46 ScopedPlatformHandle server_pipe, 47 const std::string& child_token); 48 49 // Called in the parent process for each child process that is launched. 50 // |process_error_callback| is called if the system becomes aware of some 51 // internal error related to this process, e.g., if the system is notified of a 52 // bad message from this process via the |MojoNotifyBadMessage()| API. 53 MOJO_SYSTEM_IMPL_EXPORT void ChildProcessLaunched( 54 base::ProcessHandle child_process, 55 ScopedPlatformHandle server_pipe, 56 const std::string& child_token, 57 const ProcessErrorCallback& error_callback); 58 59 // Called in the parent process when a child process fails to launch. 60 // Exactly one of ChildProcessLaunched() or ChildProcessLaunchFailed() must be 61 // called per child process launch attempt. 62 MOJO_SYSTEM_IMPL_EXPORT void ChildProcessLaunchFailed( 63 const std::string& child_token); 64 65 // Should be called as early as possible in the child process with the handle 66 // that the parent received from ChildProcessLaunched. 67 MOJO_SYSTEM_IMPL_EXPORT void SetParentPipeHandle(ScopedPlatformHandle pipe); 68 69 // Same as above but extracts the pipe handle from the command line. See 70 // PlatformChannelPair for details. 71 MOJO_SYSTEM_IMPL_EXPORT void SetParentPipeHandleFromCommandLine(); 72 73 // Must be called first, or just after setting configuration parameters, to 74 // initialize the (global, singleton) system. 75 MOJO_SYSTEM_IMPL_EXPORT void Init(); 76 77 // Basic functions ------------------------------------------------------------- 78 79 // The functions in this section are available once |Init()| has been called. 80 81 // Creates a |MojoHandle| that wraps the given |PlatformHandle| (taking 82 // ownership of it). This |MojoHandle| can then, e.g., be passed through message 83 // pipes. Note: This takes ownership (and thus closes) |platform_handle| even on 84 // failure, which is different from what you'd expect from a Mojo API, but it 85 // makes for a more convenient embedder API. 86 MOJO_SYSTEM_IMPL_EXPORT MojoResult 87 CreatePlatformHandleWrapper(ScopedPlatformHandle platform_handle, 88 MojoHandle* platform_handle_wrapper_handle); 89 90 // Retrieves the |PlatformHandle| that was wrapped into a |MojoHandle| (using 91 // |CreatePlatformHandleWrapper()| above). Note that the |MojoHandle| is closed 92 // on success. 93 MOJO_SYSTEM_IMPL_EXPORT MojoResult 94 PassWrappedPlatformHandle(MojoHandle platform_handle_wrapper_handle, 95 ScopedPlatformHandle* platform_handle); 96 97 // Creates a |MojoHandle| that wraps the given |SharedMemoryHandle| (taking 98 // ownership of it). |num_bytes| is the size of the shared memory object, and 99 // |read_only| is whether the handle is a read-only handle to shared memory. 100 // This |MojoHandle| is a Mojo shared buffer and can be manipulated using the 101 // shared buffer functions and transferred over a message pipe. 102 MOJO_SYSTEM_IMPL_EXPORT MojoResult 103 CreateSharedBufferWrapper(base::SharedMemoryHandle shared_memory_handle, 104 size_t num_bytes, 105 bool read_only, 106 MojoHandle* mojo_wrapper_handle); 107 108 // Retrieves the underlying |SharedMemoryHandle| from a shared buffer 109 // |MojoHandle| and closes the handle. If successful, |num_bytes| will contain 110 // the size of the shared memory buffer and |read_only| will contain whether the 111 // buffer handle is read-only. Both |num_bytes| and |read_only| may be null. 112 // Note: The value of |shared_memory_handle| may be 113 // base::SharedMemory::NULLHandle(), even if this function returns success. 114 // Callers should perform appropriate checks. 115 MOJO_SYSTEM_IMPL_EXPORT MojoResult 116 PassSharedMemoryHandle(MojoHandle mojo_handle, 117 base::SharedMemoryHandle* shared_memory_handle, 118 size_t* num_bytes, 119 bool* read_only); 120 121 // Initialialization/shutdown for interprocess communication (IPC) ------------- 122 123 // |InitIPCSupport()| sets up the subsystem for interprocess communication, 124 // making the IPC functions (in the following section) available and functional. 125 // (This may only be done after |Init()|.) 126 // 127 // This subsystem may be shut down using |ShutdownIPCSupport()|. None of the IPC 128 // functions may be called after this is called. 129 130 // Initializes a process of the given type; to be called after |Init()|. 131 // - |process_delegate| must be a process delegate of the appropriate type 132 // corresponding to |process_type|; its methods will be called on the same 133 // thread as Shutdown. 134 // - |process_delegate|, and |io_thread_task_runner| should live at least 135 // until |ShutdownIPCSupport()|'s callback has been run. 136 MOJO_SYSTEM_IMPL_EXPORT void InitIPCSupport( 137 ProcessDelegate* process_delegate, 138 scoped_refptr<base::TaskRunner> io_thread_task_runner); 139 140 // Shuts down the subsystem initialized by |InitIPCSupport()|. It be called from 141 // any thread and will attempt to complete shutdown on the I/O thread with which 142 // the system was initialized. Upon completion the ProcessDelegate's 143 // |OnShutdownComplete()| method is invoked. 144 MOJO_SYSTEM_IMPL_EXPORT void ShutdownIPCSupport(); 145 146 #if defined(OS_MACOSX) && !defined(OS_IOS) 147 // Set the |base::PortProvider| for this process. Can be called on any thread, 148 // but must be set in the root process before any Mach ports can be transferred. 149 MOJO_SYSTEM_IMPL_EXPORT void SetMachPortProvider( 150 base::PortProvider* port_provider); 151 #endif 152 153 // Creates a message pipe from a token. A child embedder must also have this 154 // token and call CreateChildMessagePipe() with it in order for the pipe to get 155 // connected. |child_token| identifies the child process and should be the same 156 // as the token passed into ChildProcessLaunched(). If they are different, the 157 // returned message pipe will not be signaled of peer closure if the child 158 // process dies before establishing connection to the pipe. 159 MOJO_SYSTEM_IMPL_EXPORT ScopedMessagePipeHandle 160 CreateParentMessagePipe(const std::string& token, 161 const std::string& child_token); 162 163 // Creates a message pipe from a token in a child process. The parent must also 164 // have this token and call CreateParentMessagePipe() with it in order for the 165 // pipe to get connected. 166 MOJO_SYSTEM_IMPL_EXPORT ScopedMessagePipeHandle 167 CreateChildMessagePipe(const std::string& token); 168 169 // Generates a random ASCII token string for use with CreateParentMessagePipe() 170 // and CreateChildMessagePipe() above. The generated token is suitably random so 171 // as to not have to worry about collisions with other generated tokens. 172 MOJO_SYSTEM_IMPL_EXPORT std::string GenerateRandomToken(); 173 174 // Sets system properties that can be read by the MojoGetProperty() API. See the 175 // documentation for MojoPropertyType for supported property types and their 176 // corresponding value type. 177 // 178 // Default property values: 179 // |MOJO_PROPERTY_TYPE_SYNC_CALL_ALLOWED| - true 180 MOJO_SYSTEM_IMPL_EXPORT MojoResult SetProperty(MojoPropertyType type, 181 const void* value); 182 183 } // namespace edk 184 } // namespace mojo 185 186 #endif // MOJO_EDK_EMBEDDER_EMBEDDER_H_ 187