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

mojo/public/c/system/functions.h

Index: mojo/public/c/system/functions.h
diff --git a/mojo/public/c/system/functions.h b/mojo/public/c/system/functions.h
index bd4daedaf7bbcae173861adfa171c6efe677d739..3d4d07c0fa0cb666047f965e5a95bd79b65dd1c9 100644
--- a/mojo/public/c/system/functions.h
+++ b/mojo/public/c/system/functions.h
@@ -19,6 +19,29 @@
 extern "C" {
 #endif
 
+// |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
+
 // A callback used to notify watchers registered via |MojoWatch()|. Called when
 // some watched signals are satisfied or become unsatisfiable. See the
 // documentation for |MojoWatch()| for more details.
@@ -206,6 +229,89 @@ MojoWatch(MojoHandle handle,
 MOJO_SYSTEM_EXPORT MojoResult
 MojoCancelWatch(MojoHandle handle, uintptr_t context);
 
+// Wraps a generic platform handle as a Mojo handle which can be transferred
+// over a message pipe. Takes ownership of the platform handle.
+//
+// |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
+// this call may succeed even when |handle| invalid (e.g. a valid file
+// descriptor value for a file descriptor that isn't actually open.)
+MOJO_SYSTEM_EXPORT MojoResult
+MojoWrapPlatformHandle(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
+// platform object is bound to the returned platform handle and becomes the
+// caller's responsibility.
+//
+// |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,
+                         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(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.
+//
+// |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,
+    MojoPlatformHandle* platform_handle,
+    size_t* num_bytes,
+    MojoPlatformSharedBufferHandleFlags* flags);
+
 #ifdef __cplusplus
 }  // extern "C"
 #endif