1 // Copyright 2016 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 // This file provides a C++ wrapping around the Mojo C API for platform handles, 6 // replacing the prefix of "Mojo" with a "mojo" namespace. 7 // 8 // Please see "mojo/public/c/system/platform_handle.h" for complete 9 // documentation of the API. 10 11 #ifndef MOJO_PUBLIC_CPP_SYSTEM_PLATFORM_HANDLE_H_ 12 #define MOJO_PUBLIC_CPP_SYSTEM_PLATFORM_HANDLE_H_ 13 14 #include <stdint.h> 15 16 #include "base/compiler_specific.h" 17 #include "base/files/file.h" 18 #include "base/logging.h" 19 #include "base/macros.h" 20 #include "base/memory/read_only_shared_memory_region.h" 21 #include "base/memory/shared_memory_handle.h" 22 #include "base/memory/unsafe_shared_memory_region.h" 23 #include "base/memory/writable_shared_memory_region.h" 24 #include "base/process/process_handle.h" 25 #include "build/build_config.h" 26 #include "mojo/public/c/system/platform_handle.h" 27 #include "mojo/public/cpp/platform/platform_handle.h" 28 #include "mojo/public/cpp/system/buffer.h" 29 #include "mojo/public/cpp/system/handle.h" 30 #include "mojo/public/cpp/system/system_export.h" 31 32 #if defined(OS_WIN) 33 #include <windows.h> 34 #endif 35 36 namespace mojo { 37 38 #if defined(OS_WIN) 39 const MojoPlatformHandleType kPlatformFileHandleType = 40 MOJO_PLATFORM_HANDLE_TYPE_WINDOWS_HANDLE; 41 42 const MojoPlatformHandleType kPlatformSharedBufferHandleType = 43 MOJO_PLATFORM_HANDLE_TYPE_WINDOWS_HANDLE; 44 45 #elif defined(OS_FUCHSIA) 46 const MojoPlatformHandleType kPlatformFileHandleType = 47 MOJO_PLATFORM_HANDLE_TYPE_FILE_DESCRIPTOR; 48 const MojoPlatformHandleType kPlatformSharedBufferHandleType = 49 MOJO_PLATFORM_HANDLE_TYPE_FUCHSIA_HANDLE; 50 51 #elif defined(OS_POSIX) 52 const MojoPlatformHandleType kPlatformFileHandleType = 53 MOJO_PLATFORM_HANDLE_TYPE_FILE_DESCRIPTOR; 54 55 #if defined(OS_MACOSX) && !defined(OS_IOS) 56 const MojoPlatformHandleType kPlatformSharedBufferHandleType = 57 MOJO_PLATFORM_HANDLE_TYPE_MACH_PORT; 58 #else 59 const MojoPlatformHandleType kPlatformSharedBufferHandleType = 60 MOJO_PLATFORM_HANDLE_TYPE_FILE_DESCRIPTOR; 61 #endif // defined(OS_MACOSX) && !defined(OS_IOS) 62 63 #endif // defined(OS_WIN) 64 65 // Used to specify the protection status of a base::SharedMemoryHandle memory 66 // handle wrapped or unwrapped by mojo::WrapSharedMemoryHandle or 67 // mojo::UnwrapSharedMemoryHandle below. See those functions for additional 68 // details. 69 enum class UnwrappedSharedMemoryHandleProtection { 70 // Indicates that the base::SharedMemoryHandle supports being mapped to 71 // writable memory regions. 72 kReadWrite, 73 74 // Indicates that the base::SharedMemoryHandle supports being mapped only to 75 // read-only memory regions. 76 kReadOnly, 77 }; 78 79 // Wraps a PlatformHandle from the C++ platform support library as a Mojo 80 // handle. 81 MOJO_CPP_SYSTEM_EXPORT ScopedHandle WrapPlatformHandle(PlatformHandle handle); 82 83 // Unwraps a Mojo handle to a PlatformHandle object from the C++ platform 84 // support library. 85 MOJO_CPP_SYSTEM_EXPORT PlatformHandle UnwrapPlatformHandle(ScopedHandle handle); 86 87 // Wraps a PlatformFile as a Mojo handle. Takes ownership of the file object. 88 // If |platform_file| is valid, this will return a valid handle. 89 MOJO_CPP_SYSTEM_EXPORT 90 ScopedHandle WrapPlatformFile(base::PlatformFile platform_file); 91 92 // Unwraps a PlatformFile from a Mojo handle. 93 MOJO_CPP_SYSTEM_EXPORT 94 MojoResult UnwrapPlatformFile(ScopedHandle handle, base::PlatformFile* file); 95 96 // DEPRECATED: Don't introduce new uses of base::SharedMemoryHandle, and please 97 // attempt to avoid using this function. Use the new base shared memory APIs 98 // (base::ReadOnlySharedMemoryRegion et al) and the corresponding wrap/unwrap 99 // calls defined below instead. 100 // 101 // Wraps a base::SharedMemoryHandle as a Mojo handle. Takes ownership of the 102 // SharedMemoryHandle. |size| indicates the size of the underlying 103 // base::SharedMemory object, and |current_protection| indicates whether or 104 // not |memory_handle| supports being mapped to writable memory segments. 105 // 106 // ***** IMPORTANT. PLEASE READ BELOW CAREFULLY. ***** 107 // 108 // THIS CALL DOES NOT IN ANY WAY AFFECT THE MEMORY PROTECTION STATUS OF THE 109 // WRAPPED HANDLE. 110 // 111 // The |current_protection| argument is only an indication of the current memory 112 // protection status of |memory_handle| as known by the caller. 113 // 114 // DO NOT wrap a writable |memory_handle| with |current_protection| set to 115 // |UnwrappedSharedMemoryHandleProtection::kReadOnly|, as this will mislead 116 // corresponding callers to |UnwrapSharedMemoryHandle()|: the subsequently 117 // unwrapped SharedMemoryHandle will appear to be read-only on the surface, but 118 // will still be mappable to a writable memory segment. 119 // 120 // Use base::SharedMemory::GetReadOnlyHandle() to acquire a read-only handle to 121 // a shared memory object if you intend to wrap the handle with 122 // |UnwrappedSharedMemoryHandleProtection::kReadOnly|. 123 MOJO_CPP_SYSTEM_EXPORT 124 ScopedSharedBufferHandle WrapSharedMemoryHandle( 125 const base::SharedMemoryHandle& memory_handle, 126 size_t size, 127 UnwrappedSharedMemoryHandleProtection current_protection); 128 129 // DEPRECATED: Don't introduce new uses of base::SharedMemoryHandle, and please 130 // attempt to avoid using this function. Use the new base shared memory APIs 131 // (base::ReadOnlySharedMemoryRegion et al) and the corresponding wrap/unwrap 132 // calls defined below instead. 133 // 134 // Unwraps a base::SharedMemoryHandle from a Mojo handle. The caller assumes 135 // responsibility for the lifetime of the SharedMemoryHandle. On success, 136 // |*memory_handle| is set to a valid handle, |*size| is is set to the size of 137 // that handle's underlying base::SharedMemory object, and 138 // |*protection| indicates whether or not the handle may only be mapped 139 // to a read-only memory segment. 140 // 141 // Note that if |*protection| is 142 // |UnwrappedSharedMemoryHandleProtection::kReadOnly| upon return, writable 143 // mapping of |*memory_handle| should not be attempted, and (unless there 144 // is buggy code misusing WrapSharedMemoryHandle above) will always fail. 145 MOJO_CPP_SYSTEM_EXPORT MojoResult 146 UnwrapSharedMemoryHandle(ScopedSharedBufferHandle handle, 147 base::SharedMemoryHandle* memory_handle, 148 size_t* size, 149 UnwrappedSharedMemoryHandleProtection* protection); 150 151 // Helpers for wrapping and unwrapping new base shared memory API primitives. 152 // If the input |region| is valid for the Wrap* functions, they will always 153 // succeed and return a valid Mojo shared buffer handle. 154 155 MOJO_CPP_SYSTEM_EXPORT ScopedSharedBufferHandle 156 WrapReadOnlySharedMemoryRegion(base::ReadOnlySharedMemoryRegion region); 157 158 MOJO_CPP_SYSTEM_EXPORT ScopedSharedBufferHandle 159 WrapUnsafeSharedMemoryRegion(base::UnsafeSharedMemoryRegion region); 160 161 MOJO_CPP_SYSTEM_EXPORT ScopedSharedBufferHandle 162 WrapWritableSharedMemoryRegion(base::WritableSharedMemoryRegion region); 163 164 MOJO_CPP_SYSTEM_EXPORT base::ReadOnlySharedMemoryRegion 165 UnwrapReadOnlySharedMemoryRegion(ScopedSharedBufferHandle handle); 166 167 MOJO_CPP_SYSTEM_EXPORT base::UnsafeSharedMemoryRegion 168 UnwrapUnsafeSharedMemoryRegion(ScopedSharedBufferHandle handle); 169 170 MOJO_CPP_SYSTEM_EXPORT base::WritableSharedMemoryRegion 171 UnwrapWritableSharedMemoryRegion(ScopedSharedBufferHandle handle); 172 173 #if defined(OS_MACOSX) && !defined(OS_IOS) 174 // Wraps a mach_port_t as a Mojo handle. This takes a reference to the 175 // Mach port. 176 MOJO_CPP_SYSTEM_EXPORT ScopedHandle WrapMachPort(mach_port_t port); 177 178 // Unwraps a mach_port_t from a Mojo handle. The caller gets ownership of the 179 // Mach port. 180 MOJO_CPP_SYSTEM_EXPORT MojoResult UnwrapMachPort(ScopedHandle handle, 181 mach_port_t* port); 182 #endif // defined(OS_MACOSX) && !defined(OS_IOS) 183 184 } // namespace mojo 185 186 #endif // MOJO_PUBLIC_CPP_SYSTEM_PLATFORM_HANDLE_H_ 187