[mojo-edk] Add explicit message object APIs

mojo/public/c/system/message_pipe.h

Index: mojo/public/c/system/message_pipe.h
diff --git a/mojo/public/c/system/message_pipe.h b/mojo/public/c/system/message_pipe.h
index 8c5c215eafa4c8a19a02045021d8e5fa446ecda0..29c2c5612b0ed34901ae51642507c797581f1c4d 100644
--- a/mojo/public/c/system/message_pipe.h
+++ b/mojo/public/c/system/message_pipe.h
@@ -15,6 +15,18 @@
 #include "mojo/public/c/system/system_export.h"
 #include "mojo/public/c/system/types.h"
 
+// |MojoMessageHandle|: Used to refer to message objects created by
+//     |MojoCreateMessage()| and transferred by |MojoWriteMessageNew()| or
+//     |MojoReadMessageNew()|.
+
+typedef uintptr_t MojoMessageHandle;
+
+#ifdef __cplusplus
+const MojoMessageHandle MOJO_MESSAGE_HANDLE_INVALID = 0;
+#else
+#define MOJO_MESSAGE_HANDLE_INVALID ((MojoMessageHandle)0)
+#endif
+
 // |MojoCreateMessagePipeOptions|: Used to specify creation parameters for a
 // message pipe to |MojoCreateMessagePipe()|.
 //   |uint32_t struct_size|: Set to the size of the
@@ -79,6 +91,18 @@ const MojoReadMessageFlags MOJO_READ_MESSAGE_FLAG_MAY_DISCARD = 1 << 0;
 #define MOJO_READ_MESSAGE_FLAG_MAY_DISCARD ((MojoReadMessageFlags)1 << 0)
 #endif
 
+// |MojoCreateMessageFlags|: Used to specify different options for
+// |MojoCreateMessage()|.
+//   |MOJO_CREATE_MESSAGE_FLAG_NONE| - No flags; default mode.
+
+typedef uint32_t MojoCreateMessageFlags;
+
+#ifdef __cplusplus
+const MojoCreateMessageFlags MOJO_CREATE_MESSAGE_FLAG_NONE = 0;
+#else
+#define MOJO_CREATE_MESSAGE_FLAG_NONE ((MojoCreateMessageFlags)0)
+#endif
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -142,6 +166,17 @@ MOJO_SYSTEM_EXPORT MojoResult
                      uint32_t num_handles,
                      MojoWriteMessageFlags flags);
 
+// Writes a message to the message pipe endpoint given by |message_pipe_handle|.
+//
+// |message|: A message object created by |MojoCreateMessage()|. Ownership of
+//     the message is passed into Mojo.
+//
+// Returns results corresponding to |MojoWriteMessage()| above.
+MOJO_SYSTEM_EXPORT MojoResult
+    MojoWriteMessageNew(MojoHandle message_pipe_handle,
+                        MojoMessageHandle message,
+                        MojoWriteMessageFlags);
+
 // Reads the next message from a message pipe, or indicates the size of the
 // message if it cannot fit in the provided buffers. The message will be read
 // in its entirety or not at all; if it is not, it will remain enqueued unless
@@ -181,6 +216,30 @@ MOJO_SYSTEM_EXPORT MojoResult
                     uint32_t* num_handles,  // Optional in/out.
                     MojoReadMessageFlags flags);
 
+// Reads the next message from a message pipe and returns an address to a
+// message containing the message bytes. The returned message must eventually be
+// freed using |MojoDestroyMessage()|.
+//
+// Message payload can be accessed using |MojoGetMessageBuffer()|.
+//
+//   |message_pipe_handle|, |num_bytes|, |handles|, |num_handles|, and |flags|
+//       correspond to their use in |MojoReadMessage()| above, with the
+//       exception that |num_bytes| is only an output argument.
+//   |message| must be non-null unless |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| is
+//       set in flags.
+//
+// Return values correspond to the return values for |MojoReadMessage()| above.
+// On success (MOJO_RESULT_OK), |*message| will contain the address of a
+// message object which may be passed to |MojoGetMessageBuffer()| and/or
+// |MojoDestroyMessage()|.
+MOJO_SYSTEM_EXPORT MojoResult
+    MojoReadMessageNew(MojoHandle message_pipe_handle,
+                       MojoMessageHandle* message,  // Optional out.
+                       uint32_t* num_bytes,         // Optional out.
+                       MojoHandle* handles,         // Optional out.
+                       uint32_t* num_handles,       // Optional in/out.
+                       MojoReadMessageFlags flags);
+
 // Fuses two message pipe endpoints together. Given two pipes:
 //
 //     A <-> B    and    C <-> D
@@ -205,6 +264,63 @@ MOJO_SYSTEM_EXPORT MojoResult
 MOJO_SYSTEM_EXPORT MojoResult
     MojoFuseMessagePipes(MojoHandle handle0, MojoHandle handle1);
 
+// Allocates a new message whose ownership may be passed to
+// |MojoWriteMessageNew()|. Use |MojoGetMessageBuffer()| to retrieve the address
+// of the mutable message payload.
+//
+// |num_bytes|: The size of the message payload in bytes.
+// |handles|: An array of handles to transfer in the message. This takes
+//     ownership of and invalidates all contained handles. Must be null if and
+//     only if |num_handles| is 0.
+// |num_handles|: The number of handles contained in |handles|.
+// |flags|: Must be |MOJO_CREATE_MESSAGE_FLAG_NONE|.
+// |message|: The address of a pointer to be filled with the new message's
+//     address. Must be non-null.
+//
+// Returns:
+//   |MOJO_RESULT_OK| if the message was successfully allocated. In this case
+//       |*message| will be populated with the address of an allocated message
+//       large enough to hold at least |num_bytes| contiguous bytes.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if one or more handles in |handles| was
+//       invalid, or |handles| was null with a non-zero |num_handles|.
+//   |MOJO_RESULT_RESOURCE_EXHAUSTED| if allocation failed because either
+//       |num_bytes| or |num_handles| exceeds an implementation-defined maximum.
+//   |MOJO_RESULT_BUSY| if one or more handles in |handles| cannot be sent at
+//       the time of this call.
+//
+// Only upon successful message allocation will all handles in |handles| be
+// transferred into the message and invalidated.
+MOJO_SYSTEM_EXPORT MojoResult
+MojoCreateMessage(uint32_t num_bytes,
+                  const MojoHandle* handles,
+                  uint32_t num_handles,
+                  MojoCreateMessageFlags flags,
+                  MojoMessageHandle* message);  // Out
+
+// Destroys a message allocated by |MojoCreateMessage()| or
+// |MojoReadMessageNew()|.
+//
+// |message|: The address of the message to destroy. This must correspond to a
+//     message previously created by |MojoCreateMessage()| or
+//     |MojoReadMessageNew()|. Note that if the message has already been passed
+//     to |MojoWriteMessageNew()| it should NOT also be destroyed with this API.
+//
+// Returns:
+//   |MOJO_RESULT_OK| if |message| was valid and has been destroyed.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if |message| was not a valid message object.
+MOJO_SYSTEM_EXPORT MojoResult MojoDestroyMessage(MojoMessageHandle message);
+
+// Retrieves the address of mutable message bytes for a message created by
+// either |MojoCreateMessage()| or |MojoReadMessageNew()|.
+//
+// |message|: The message object.
+//
+// Returns:
+//   |MOJO_RESULT_OK| if |message| is a valid message object. |*buffer| will
+//       be updated to point to mutable message bytes.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if |message| is not a valid message object.
+MOJO_SYSTEM_EXPORT MojoResult MojoGetMessageBuffer(MojoMessageHandle message,
+                                                   void** buffer);  // Out
 
 #ifdef __cplusplus
 }  // extern "C"