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

mojo/public/c/system/functions.h

 // Copyright 2014 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 basic functions common to different Mojo system APIs.
 //
 // Note: This header should be compilable as C.
 
 #ifndef MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_
 #define MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_
 
 #include <stddef.h>
 #include <stdint.h>
 
 #include "mojo/public/c/system/system_export.h"
 #include "mojo/public/c/system/types.h"
 
 #ifdef __cplusplus
 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.
 typedef void (*MojoWatchCallback)(uintptr_t context,
                                   MojoResult result,
                                   struct MojoHandleSignalsState signals_state,
                                   MojoWatchNotificationFlags flags);
 
 // Note: Pointer parameters that are labelled "optional" may be null (at least
 // under some circumstances). Non-const pointer parameters are also labeled
@@ skipping 167 matching lines @@
 //     |MojoWatch()|. Only the watch corresponding to this context will be
 //     cancelled.
 //
 // Returns:
 //     |MOJO_RESULT_OK| if the watch corresponding to |context| was cancelled.
 //     |MOJO_RESULT_INVALID_ARGUMENT| if no watch was registered with |context|
 //         for the given |handle|, or if |handle| is invalid.
 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
 
 #endif  // MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_