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 contains types/functions and constants for platform handle wrapping 6 // and unwrapping APIs. 7 // 8 // Note: This header should be compilable as C. 9 10 #ifndef MOJO_PUBLIC_C_SYSTEM_PLATFORM_HANDLE_H_ 11 #define MOJO_PUBLIC_C_SYSTEM_PLATFORM_HANDLE_H_ 12 13 #include <stdint.h> 14 15 #include "mojo/public/c/system/system_export.h" 16 #include "mojo/public/c/system/types.h" 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 // |MojoPlatformHandleType|: A value indicating the specific type of platform 23 // handle encapsulated by a MojoPlatformHandle (see below.) This is stored 24 // in the MojoPlatformHandle's |type| field and determines how the |value| 25 // field is interpreted. 26 // 27 // |MOJO_PLATFORM_HANDLE_TYPE_INVALID| - An invalid platform handle. 28 // |MOJO_PLATFORM_HANDLE_TYPE_FILE_DESCRIPTOR| - A file descriptor. Only valid 29 // on POSIX systems. 30 // |MOJO_PLATFORM_HANDLE_TYPE_MACH_PORT| - A Mach port. Only valid on OS X. 31 // |MOJO_PLATFORM_HANDLE_TYPE_WINDOWS_HANDLE| - A Windows HANDLE value. Only 32 // valid on Windows. 33 34 typedef uint32_t MojoPlatformHandleType; 35 36 #ifdef __cplusplus 37 const MojoPlatformHandleType MOJO_PLATFORM_HANDLE_TYPE_INVALID = 0; 38 const MojoPlatformHandleType MOJO_PLATFORM_HANDLE_TYPE_FILE_DESCRIPTOR = 1; 39 const MojoPlatformHandleType MOJO_PLATFORM_HANDLE_TYPE_MACH_PORT = 2; 40 const MojoPlatformHandleType MOJO_PLATFORM_HANDLE_TYPE_WINDOWS_HANDLE = 3; 41 #else 42 #define MOJO_PLATFORM_HANDLE_TYPE_INVALID ((MojoPlatformHandleType)0) 43 #define MOJO_PLATFORM_HANDLE_TYPE_FILE_DESCRIPTOR ((MojoPlatformHandleType)1) 44 #define MOJO_PLATFORM_HANDLE_TYPE_MACH_PORT ((MojoPlatformHandleType)2) 45 #define MOJO_PLATFORM_HANDLE_TYPE_WINDOWS_HANDLE ((MojoPlatformHandleType)3) 46 #endif 47 48 // |MojoPlatformHandle|: A handle to an OS object. 49 // |uint32_t struct_size|: The size of this structure. Used for versioning 50 // to allow for future extensions. 51 // |MojoPlatformHandleType type|: The type of handle stored in |value|. 52 // |uint64_t value|: The value of this handle. Ignored if |type| is 53 // MOJO_PLATFORM_HANDLE_TYPE_INVALID. 54 // 55 56 struct MOJO_ALIGNAS(8) MojoPlatformHandle { 57 uint32_t struct_size; 58 MojoPlatformHandleType type; 59 uint64_t value; 60 }; 61 MOJO_STATIC_ASSERT(sizeof(MojoPlatformHandle) == 16, 62 "MojoPlatformHandle has wrong size"); 63 64 // |MojoPlatformSharedBufferHandleFlags|: Flags relevant to wrapped platform 65 // shared buffers. 66 // 67 // |MOJO_PLATFORM_SHARED_BUFFER_HANDLE_NONE| - No flags. 68 // |MOJO_PLATFORM_SHARED_BUFFER_HANDLE_READ_ONLY| - Indicates that the wrapped 69 // buffer handle may only be mapped for reading. 70 71 typedef uint32_t MojoPlatformSharedBufferHandleFlags; 72 73 #ifdef __cplusplus 74 const MojoPlatformSharedBufferHandleFlags 75 MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_NONE = 0; 76 77 const MojoPlatformSharedBufferHandleFlags 78 MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_READ_ONLY = 1 << 0; 79 #else 80 #define MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_NONE \ 81 ((MojoPlatformSharedBufferHandleFlags)0) 82 83 #define MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_READ_ONLY \ 84 ((MojoPlatformSharedBufferHandleFlags)1 << 0) 85 #endif 86 87 // Wraps a generic platform handle as a Mojo handle which can be transferred 88 // over a message pipe. Takes ownership of the underlying platform object. 89 // 90 // |platform_handle|: The platform handle to wrap. 91 // 92 // Returns: 93 // |MOJO_RESULT_OK| if the handle was successfully wrapped. In this case 94 // |*mojo_handle| contains the Mojo handle of the wrapped object. 95 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if the system is out of handles. 96 // |MOJO_RESULT_INVALID_ARGUMENT| if |platform_handle| was not a valid 97 // platform handle. 98 // 99 // NOTE: It is not always possible to detect if |platform_handle| is valid, 100 // particularly when |platform_handle->type| is valid but 101 // |platform_handle->value| does not represent a valid platform object. 102 MOJO_SYSTEM_EXPORT MojoResult 103 MojoWrapPlatformHandle(const struct MojoPlatformHandle* platform_handle, 104 MojoHandle* mojo_handle); // Out 105 106 // Unwraps a generic platform handle from a Mojo handle. If this call succeeds, 107 // ownership of the underlying platform object is bound to the returned platform 108 // handle and becomes the caller's responsibility. The Mojo handle is always 109 // closed regardless of success or failure. 110 // 111 // |mojo_handle|: The Mojo handle from which to unwrap the platform handle. 112 // 113 // Returns: 114 // |MOJO_RESULT_OK| if the handle was successfully unwrapped. In this case 115 // |*platform_handle| contains the unwrapped platform handle. 116 // |MOJO_RESULT_INVALID_ARGUMENT| if |mojo_handle| was not a valid Mojo 117 // handle wrapping a platform handle. 118 MOJO_SYSTEM_EXPORT MojoResult 119 MojoUnwrapPlatformHandle(MojoHandle mojo_handle, 120 struct MojoPlatformHandle* platform_handle); // Out 121 122 // Wraps a platform shared buffer handle as a Mojo shared buffer handle which 123 // can be transferred over a message pipe. Takes ownership of the platform 124 // shared buffer handle. 125 // 126 // |platform_handle|: The platform handle to wrap. Must be a handle to a 127 // shared buffer object. 128 // |num_bytes|: The size of the shared buffer in bytes. 129 // |flags|: Flags which influence the treatment of the shared buffer object. See 130 // below. 131 // 132 // Flags: 133 // |MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_NONE| indicates default behavior. 134 // No flags set. 135 // |MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_READ_ONLY| indicates that the 136 // buffer handled to be wrapped may only be mapped as read-only. This 137 // flag does NOT change the access control of the buffer in any way. 138 // 139 // Returns: 140 // |MOJO_RESULT_OK| if the handle was successfully wrapped. In this case 141 // |*mojo_handle| contains a Mojo shared buffer handle. 142 // |MOJO_RESULT_INVALID_ARGUMENT| if |platform_handle| was not a valid 143 // platform shared buffer handle. 144 MOJO_SYSTEM_EXPORT MojoResult 145 MojoWrapPlatformSharedBufferHandle( 146 const struct MojoPlatformHandle* platform_handle, 147 size_t num_bytes, 148 MojoPlatformSharedBufferHandleFlags flags, 149 MojoHandle* mojo_handle); // Out 150 151 // Unwraps a platform shared buffer handle from a Mojo shared buffer handle. 152 // If this call succeeds, ownership of the underlying shared buffer object is 153 // bound to the returned platform handle and becomes the caller's 154 // responsibility. The Mojo handle is always closed regardless of success or 155 // failure. 156 // 157 // |mojo_handle|: The Mojo shared buffer handle to unwrap. 158 // 159 // |platform_handle|, |num_bytes| and |flags| are used to receive output values 160 // and MUST always be non-null. 161 // 162 // Returns: 163 // |MOJO_RESULT_OK| if the handle was successfully unwrapped. In this case 164 // |*platform_handle| contains a platform shared buffer handle, 165 // |*num_bytes| contains the size of the shared buffer object, and 166 // |*flags| indicates flags relevant to the wrapped buffer (see below). 167 // |MOJO_RESULT_INVALID_ARGUMENT| if |mojo_handle| is not a valid Mojo 168 // shared buffer handle. 169 // 170 // Flags which may be set in |*flags| upon success: 171 // |MOJO_PLATFORM_SHARED_BUFFER_FLAG_READ_ONLY| is set iff the unwrapped 172 // shared buffer handle may only be mapped as read-only. 173 MOJO_SYSTEM_EXPORT MojoResult 174 MojoUnwrapPlatformSharedBufferHandle( 175 MojoHandle mojo_handle, 176 struct MojoPlatformHandle* platform_handle, 177 size_t* num_bytes, 178 MojoPlatformSharedBufferHandleFlags* flags); 179 180 #ifdef __cplusplus 181 } // extern "C" 182 #endif 183 184 #endif // MOJO_PUBLIC_C_SYSTEM_PLATFORM_HANDLE_H_ 185