[mojo-edk] Expose portable API for platform handle wrapping

mojo/public/c/system/platform_handle.h

+// 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 an OS 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.
+//
+
+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 generic platform handle as a Mojo handle which can be transferred
+// over a message pipe. Takes ownership of the underlying 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 alwawys possible to detect if |platform_handle| is valid, so

[Anand Mistry (off Chromium), 2016/05/23 07:16:52]

s/alwawys/always

[Ken Rockot(use gerrit already), 2016/05/23 17:17:53]

done

+// this call may succeed even when |handle| invalid (e.g. a valid file

[Anand Mistry (off Chromium), 2016/05/23 07:16:52]

s/|handle|/|platform_handle|

Also, I think you really mean |platform_handle->value|, but now I'm really nit
picking.

[Ken Rockot(use gerrit already), 2016/05/23 17:17:53]

I do - it used to be called |handle|. In any case, I tried to clarify the docs
here.

+// descriptor value for a file descriptor that isn't actually open.)
+MOJO_SYSTEM_EXPORT MojoResult
+MojoWrapPlatformHandle(const struct MojoPlatformHandle* platform_handle,
+                       MojoHandle* mojo_handle);  // Out
+
+// Unwraps a generic platform handle from a Mojo handle. If this call succeeds,
+// the Mojo handle is closed. If this call succeeds, ownership of the underlying

[Anand Mistry (off Chromium), 2016/05/23 07:16:52]

"the mojo handle is closed"
This sentence is redundant based on the last sentence "the mojo handle is always
closed". Also, this and the next sentence don't flow well (they both begin with
"if this call succeeds").

[Ken Rockot(use gerrit already), 2016/05/23 17:17:53]

Fixed.

+// platform object is bound to the returned platform handle and becomes the
+// caller's responsibility. The Mojo handle is always closed regardless of
+// success or failure.
+//
+// |mojo_handle|: The Mojo handle from which to unwrap the 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 platform shared buffer handle as a Mojo shared buffer handle which
+// can be transferred over a message pipe. Takes ownership of the platform
+// shared buffer handle.
+//
+// |platform_handle|: The platform handle to wrap. Must be a handle to a
+//     shared buffer object.
+// |num_bytes|: The size of the shared buffer in bytes.
+//
+// NOTE: Set |MOJO_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_READ_ONLY| in |flags| if
+// the buffer to be wrapped is already 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 platform shared buffer handle from a Mojo shared buffer handle.
+// If this call succeeds, ownership of the underlying shared buffer object is
+// bound to the returned platform handle and becomes the caller's
+// responsibility. The Mojo handle is always closed regardless of success or
+// failure.
+//
+// |mojo_handle|: The Mojo shared buffer handle to unwrap.
+//
+// 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 used for read-only mapping.
+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_