| // Copyright 2016 The Chromium Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| // This file contains types/functions and constants for platform handle wrapping |
| // and unwrapping APIs. |
| // |
| // Note: This header should be compilable as C. |
| |
| #ifndef MOJO_PUBLIC_C_SYSTEM_PLATFORM_HANDLE_H_ |
| #define MOJO_PUBLIC_C_SYSTEM_PLATFORM_HANDLE_H_ |
| |
| #include <stdint.h> |
| |
| #include "mojo/public/c/system/system_export.h" |
| #include "mojo/public/c/system/types.h" |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| // |MojoPlatformHandleType|: A value indicating the specific type of platform |
| // handle encapsulated by a MojoPlatformHandle (see below.) This is stored |
| // in the MojoPlatformHandle's |type| field and determines how the |value| |
| // field is interpreted. |
| // |
| // |MOJO_PLATFORM_HANDLE_TYPE_INVALID| - An invalid platform handle. |
| // |MOJO_PLATFORM_HANDLE_TYPE_FILE_DESCRIPTOR| - A file descriptor. Only valid |
| // on POSIX systems. |
| // |MOJO_PLATFORM_HANDLE_TYPE_MACH_PORT| - A Mach port. Only valid on OS X. |
| // |MOJO_PLATFORM_HANDLE_TYPE_WINDOWS_HANDLE| - A Windows HANDLE value. Only |
| // valid on Windows. |
| |
| typedef uint32_t MojoPlatformHandleType; |
| |
| #ifdef __cplusplus |
| const MojoPlatformHandleType MOJO_PLATFORM_HANDLE_TYPE_INVALID = 0; |
| const MojoPlatformHandleType MOJO_PLATFORM_HANDLE_TYPE_FILE_DESCRIPTOR = 1; |
| const MojoPlatformHandleType MOJO_PLATFORM_HANDLE_TYPE_MACH_PORT = 2; |
| const MojoPlatformHandleType MOJO_PLATFORM_HANDLE_TYPE_WINDOWS_HANDLE = 3; |
| #else |
| #define MOJO_PLATFORM_HANDLE_TYPE_INVALID ((MojoPlatformHandleType)0) |
| #define MOJO_PLATFORM_HANDLE_TYPE_FILE_DESCRIPTOR ((MojoPlatformHandleType)1) |
| #define MOJO_PLATFORM_HANDLE_TYPE_MACH_PORT ((MojoPlatformHandleType)2) |
| #define MOJO_PLATFORM_HANDLE_TYPE_WINDOWS_HANDLE ((MojoPlatformHandleType)3) |
| #endif |
| |
| // |MojoPlatformHandle|: A handle to a native platform object. |
| // |
| // |uint32_t struct_size|: The size of this structure. Used for versioning |
| // to allow for future extensions. |
| // |
| // |MojoPlatformHandleType type|: The type of handle stored in |value|. |
| // |
| // |uint64_t value|: The value of this handle. Ignored if |type| is |
| // MOJO_PLATFORM_HANDLE_TYPE_INVALID. Otherwise the meaning of this |
| // value depends on the value of |type|. |
| // |
| |
| struct MOJO_ALIGNAS(8) MojoPlatformHandle { |
| uint32_t struct_size; |
| MojoPlatformHandleType type; |
| uint64_t value; |
| }; |
| MOJO_STATIC_ASSERT(sizeof(MojoPlatformHandle) == 16, |
| "MojoPlatformHandle has wrong size"); |
| |
| // |MojoPlatformSharedBufferHandleFlags|: Flags relevant to wrapped platform |
| // shared buffers. |
| // |
| // |MOJO_PLATFORM_SHARED_BUFFER_HANDLE_NONE| - No flags. |
| // |MOJO_PLATFORM_SHARED_BUFFER_HANDLE_READ_ONLY| - Indicates that the wrapped |
| // buffer handle may only be mapped for reading. |
| |
| typedef uint32_t MojoPlatformSharedBufferHandleFlags; |
| |
| #ifdef __cplusplus |
| const MojoPlatformSharedBufferHandleFlags |
| MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_NONE = 0; |
| |
| const MojoPlatformSharedBufferHandleFlags |
| MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_READ_ONLY = 1 << 0; |
| #else |
| #define MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_NONE \ |
| ((MojoPlatformSharedBufferHandleFlags)0) |
| |
| #define MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_READ_ONLY \ |
| ((MojoPlatformSharedBufferHandleFlags)1 << 0) |
| #endif |
| |
| // Wraps a native platform handle as a Mojo handle which can be transferred |
| // over a message pipe. Takes ownership of the underlying native platform |
| // object. |
| // |
| // |platform_handle|: The platform handle to wrap. |
| // |
| // Returns: |
| // |MOJO_RESULT_OK| if the handle was successfully wrapped. In this case |
| // |*mojo_handle| contains the Mojo handle of the wrapped object. |
| // |MOJO_RESULT_RESOURCE_EXHAUSTED| if the system is out of handles. |
| // |MOJO_RESULT_INVALID_ARGUMENT| if |platform_handle| was not a valid |
| // platform handle. |
| // |
| // NOTE: It is not always possible to detect if |platform_handle| is valid, |
| // particularly when |platform_handle->type| is valid but |
| // |platform_handle->value| does not represent a valid platform object. |
| MOJO_SYSTEM_EXPORT MojoResult |
| MojoWrapPlatformHandle(const struct MojoPlatformHandle* platform_handle, |
| MojoHandle* mojo_handle); // Out |
| |
| // Unwraps a native platform handle from a Mojo handle. If this call succeeds, |
| // ownership of the underlying platform object is assumed by the caller. The |
| // The Mojo handle is always closed regardless of success or failure. |
| // |
| // |mojo_handle|: The Mojo handle from which to unwrap the native platform |
| // handle. |
| // |
| // Returns: |
| // |MOJO_RESULT_OK| if the handle was successfully unwrapped. In this case |
| // |*platform_handle| contains the unwrapped platform handle. |
| // |MOJO_RESULT_INVALID_ARGUMENT| if |mojo_handle| was not a valid Mojo |
| // handle wrapping a platform handle. |
| MOJO_SYSTEM_EXPORT MojoResult |
| MojoUnwrapPlatformHandle(MojoHandle mojo_handle, |
| struct MojoPlatformHandle* platform_handle); // Out |
| |
| // Wraps a native platform shared buffer handle as a Mojo shared buffer handle |
| // which can be used exactly like a shared buffer handle created by |
| // |MojoCreateSharedBuffer()| or |MojoDuplicateBufferHandle()|. |
| // |
| // Takes ownership of the native platform shared buffer handle. |
| // |
| // |platform_handle|: The platform handle to wrap. Must be a native handle to a |
| // shared buffer object. |
| // |num_bytes|: The size of the shared buffer in bytes. |
| // |flags|: Flags which influence the treatment of the shared buffer object. See |
| // below. |
| // |
| // Flags: |
| // |MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_NONE| indicates default behavior. |
| // No flags set. |
| // |MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_READ_ONLY| indicates that the |
| // buffer handled to be wrapped may only be mapped as read-only. This |
| // flag does NOT change the access control of the buffer in any way. |
| // |
| // Returns: |
| // |MOJO_RESULT_OK| if the handle was successfully wrapped. In this case |
| // |*mojo_handle| contains a Mojo shared buffer handle. |
| // |MOJO_RESULT_INVALID_ARGUMENT| if |platform_handle| was not a valid |
| // platform shared buffer handle. |
| MOJO_SYSTEM_EXPORT MojoResult |
| MojoWrapPlatformSharedBufferHandle( |
| const struct MojoPlatformHandle* platform_handle, |
| size_t num_bytes, |
| MojoPlatformSharedBufferHandleFlags flags, |
| MojoHandle* mojo_handle); // Out |
| |
| // Unwraps a native platform shared buffer handle from a Mojo shared buffer |
| // handle. If this call succeeds, ownership of the underlying shared buffer |
| // object is assumed by the caller. |
| // |
| // The Mojo handle is always closed regardless of success or failure. |
| // |
| // |mojo_handle|: The Mojo shared buffer handle to unwrap. |
| // |
| // |platform_handle|, |num_bytes| and |flags| are used to receive output values |
| // and MUST always be non-null. |
| // |
| // Returns: |
| // |MOJO_RESULT_OK| if the handle was successfully unwrapped. In this case |
| // |*platform_handle| contains a platform shared buffer handle, |
| // |*num_bytes| contains the size of the shared buffer object, and |
| // |*flags| indicates flags relevant to the wrapped buffer (see below). |
| // |MOJO_RESULT_INVALID_ARGUMENT| if |mojo_handle| is not a valid Mojo |
| // shared buffer handle. |
| // |
| // Flags which may be set in |*flags| upon success: |
| // |MOJO_PLATFORM_SHARED_BUFFER_FLAG_READ_ONLY| is set iff the unwrapped |
| // shared buffer handle may only be mapped as read-only. |
| MOJO_SYSTEM_EXPORT MojoResult |
| MojoUnwrapPlatformSharedBufferHandle( |
| MojoHandle mojo_handle, |
| struct MojoPlatformHandle* platform_handle, |
| size_t* num_bytes, |
| MojoPlatformSharedBufferHandleFlags* flags); |
| |
| #ifdef __cplusplus |
| } // extern "C" |
| #endif |
| |
| #endif // MOJO_PUBLIC_C_SYSTEM_PLATFORM_HANDLE_H_ |