Enforce/require MOJO_HANDLE_RIGHT_TRANSFER in sending handles via MojoWriteMessage().

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 ea3dcc30e4a505b742d20faaff291e44f01799aa..166e08f7d58686ddf3bad26020fa85d1a6af14f0 100644
--- a/mojo/public/c/system/message_pipe.h
+++ b/mojo/public/c/system/message_pipe.h
@@ -99,7 +99,8 @@ MojoResult MojoCreateMessagePipe(
 //       |message_pipe_handle| is not a valid handle, or some of the
 //       requirements above are not satisfied).
 //   |MOJO_RESULT_PERMISSION_DENIED| if |message_pipe_handle| does not have the
-//       |MOJO_HANDLE_RIGHT_WRITE| right.
+//       |MOJO_HANDLE_RIGHT_WRITE| right or if one of the handles to be sent
+//       does not have the |MOJO_HANDLE_RIGHT_TRANSFER| right.
 //   |MOJO_RESULT_RESOURCE_EXHAUSTED| if some system limit has been reached, or
 //       the number of handles to send is too large (TODO(vtl): reconsider the
 //       latter case).
@@ -113,6 +114,15 @@ MojoResult MojoCreateMessagePipe(
 //       being sent in a message), or if some handle to be sent is currently in
 //       use.
 //
+// Note: |MOJO_RESULT_BUSY| is generally "preferred" over

[azani, 2016/05/25 03:23:53]

I'm curious as to why that is. It seems like it's an implementation detail but
your documenting it here implies it is significant to the interface. Can you
document why that decision was made here?

+// |MOJO_RESULT_PERMISSION_DENIED|. E.g., if a handle to be sent both is busy
+// and does not have the transfer right, then the result will be "busy".
+//
+// TODO(vtl): We'll also report |MOJO_RESULT_BUSY| if a (data pipe
+// producer/consumer) handle to be sent is in a two-phase write/read). But
+// should we? (For comparison, there's no such provision in |MojoClose()|.)
+// https://github.com/domokit/mojo/issues/782
+//
 // TODO(vtl): Add a notion of capacity for message pipes, and return
 // |MOJO_RESULT_SHOULD_WAIT| if the message pipe is full.
 MojoResult MojoWriteMessage(MojoHandle message_pipe_handle,  // In.