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

mojo/public/c/system/message_pipe.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 types/constants and functions specific to message pipes.
 //
 // Note: This header should be compilable as C.
 
 #ifndef MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_
 #define MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_
@@ skipping 81 matching lines @@
 // receiver will receive equivalent, but logically different, handles). Handles
 // to be sent should not be in simultaneous use (e.g., on another thread). On
 // failure, any handles to be attached will remain valid.
 //
 // Returns:
 //   |MOJO_RESULT_OK| on success (i.e., the message was enqueued).
 //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if
 //       |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).
 //   |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed.
 //       Note that closing an endpoint is not necessarily synchronous (e.g.,
 //       across processes), so this function may succeed even if the other
 //       endpoint has been closed (in which case the message would be dropped).
 //   |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|.
 //   |MOJO_RESULT_BUSY| if |message_pipe_handle| is currently in use in some
 //       transaction (that, e.g., may result in it being invalidated, such as
 //       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.
                             const void* bytes,               // Optional in.
                             uint32_t num_bytes,              // In.
                             const MojoHandle* handles,       // Optional in.
                             uint32_t num_handles,            // In.
                             MojoWriteMessageFlags flags);    // In.
 
 // |MojoReadMessage()|: Reads the next message from the message pipe endpoint
@@ skipping 37 matching lines @@
     MojoHandle message_pipe_handle,       // In.
     void* MOJO_RESTRICT bytes,            // Optional out.
     uint32_t* MOJO_RESTRICT num_bytes,    // Optional in/out.
     MojoHandle* MOJO_RESTRICT handles,    // Optional out.
     uint32_t* MOJO_RESTRICT num_handles,  // Optional in/out.
     MojoReadMessageFlags flags);          // In.
 
 MOJO_END_EXTERN_C
 
 #endif  // MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_