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/pending_process_connection.h" 20 #include "mojo/edk/embedder/scoped_platform_handle.h" 21 #include "mojo/edk/system/system_impl_export.h" 22 #include "mojo/public/cpp/system/message_pipe.h" 23 24 namespace base { 25 class PortProvider; 26 } 27 28 namespace mojo { 29 namespace edk { 30 31 // Basic configuration/initialization ------------------------------------------ 32 33 // |Init()| sets up the basic Mojo system environment, making the |Mojo...()| 34 // functions available and functional. This is never shut down (except in tests 35 // -- see test_embedder.h). 36 37 // Allows changing the default max message size. Must be called before Init. 38 MOJO_SYSTEM_IMPL_EXPORT void SetMaxMessageSize(size_t bytes); 39 40 // Should be called as early as possible in a child process with a handle to the 41 // other end of a pipe provided in the parent to 42 // PendingProcessConnection::Connect. 43 MOJO_SYSTEM_IMPL_EXPORT void SetParentPipeHandle(ScopedPlatformHandle pipe); 44 45 // Same as above but extracts the pipe handle from the command line. See 46 // PlatformChannelPair for details. 47 MOJO_SYSTEM_IMPL_EXPORT void SetParentPipeHandleFromCommandLine(); 48 49 // Called to connect to a peer process. This should be called only if there 50 // is no common ancestor for the processes involved within this mojo system. 51 // Both processes must call this function, each passing one end of a platform 52 // channel. This returns one end of a message pipe to each process. 53 MOJO_SYSTEM_IMPL_EXPORT ScopedMessagePipeHandle 54 ConnectToPeerProcess(ScopedPlatformHandle pipe); 55 56 // Called to connect to a peer process. This should be called only if there 57 // is no common ancestor for the processes involved within this mojo system. 58 // Both processes must call this function, each passing one end of a platform 59 // channel. This returns one end of a message pipe to each process. |peer_token| 60 // may be passed to ClosePeerConnection() to close the connection. 61 MOJO_SYSTEM_IMPL_EXPORT ScopedMessagePipeHandle 62 ConnectToPeerProcess(ScopedPlatformHandle pipe, const std::string& peer_token); 63 64 // Closes a connection to a peer process created by ConnectToPeerProcess() 65 // where the same |peer_token| was used. 66 MOJO_SYSTEM_IMPL_EXPORT void ClosePeerConnection(const std::string& peer_token); 67 68 // Must be called first, or just after setting configuration parameters, to 69 // initialize the (global, singleton) system. 70 MOJO_SYSTEM_IMPL_EXPORT void Init(); 71 72 // Sets a default callback to invoke when an internal error is reported but 73 // cannot be associated with a specific child process. 74 MOJO_SYSTEM_IMPL_EXPORT void SetDefaultProcessErrorCallback( 75 const ProcessErrorCallback& callback); 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 // |io_thread_task_runner| should live at least until |ShutdownIPCSupport()|'s 131 // callback has been run. 132 MOJO_SYSTEM_IMPL_EXPORT void InitIPCSupport( 133 scoped_refptr<base::TaskRunner> io_thread_task_runner); 134 135 // Retrieves the TaskRunner used for IPC I/O, as set by InitIPCSupport. 136 MOJO_SYSTEM_IMPL_EXPORT scoped_refptr<base::TaskRunner> GetIOTaskRunner(); 137 138 // Shuts down the subsystem initialized by |InitIPCSupport()|. It be called from 139 // any thread and will attempt to complete shutdown on the I/O thread with which 140 // the system was initialized. Upon completion, |callback| is invoked on an 141 // arbitrary thread. 142 MOJO_SYSTEM_IMPL_EXPORT void ShutdownIPCSupport(const base::Closure& callback); 143 144 #if defined(OS_MACOSX) && !defined(OS_IOS) 145 // Set the |base::PortProvider| for this process. Can be called on any thread, 146 // but must be set in the root process before any Mach ports can be transferred. 147 MOJO_SYSTEM_IMPL_EXPORT void SetMachPortProvider( 148 base::PortProvider* port_provider); 149 #endif 150 151 // Creates a message pipe from a token in a child process. This token must have 152 // been acquired by a corresponding call to 153 // PendingProcessConnection::CreateMessagePipe. 154 MOJO_SYSTEM_IMPL_EXPORT ScopedMessagePipeHandle 155 CreateChildMessagePipe(const std::string& token); 156 157 // Generates a random ASCII token string for use with various APIs that expect 158 // a globally unique token string. 159 MOJO_SYSTEM_IMPL_EXPORT std::string GenerateRandomToken(); 160 161 // Sets system properties that can be read by the MojoGetProperty() API. See the 162 // documentation for MojoPropertyType for supported property types and their 163 // corresponding value type. 164 // 165 // Default property values: 166 // |MOJO_PROPERTY_TYPE_SYNC_CALL_ALLOWED| - true 167 MOJO_SYSTEM_IMPL_EXPORT MojoResult SetProperty(MojoPropertyType type, 168 const void* value); 169 170 } // namespace edk 171 } // namespace mojo 172 173 #endif // MOJO_EDK_EMBEDDER_EMBEDDER_H_ 174