text: // 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_
  
  #include <stdint.h>
  
  #include "mojo/public/c/system/macros.h"
  #include "mojo/public/c/system/system_export.h"
  #include "mojo/public/c/system/types.h"
  
  // |MojoMessageHandle|: Used to refer to message objects created by
  //     |MojoAllocMessage()| 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
  //       |MojoCreateMessagePipeOptions| struct. (Used to allow for future
  //       extensions.)
  //   |MojoCreateMessagePipeOptionsFlags flags|: Used to specify different modes
  //       of operation.
  //       |MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE|: No flags; default mode.
  
  typedef uint32_t MojoCreateMessagePipeOptionsFlags;
  
  #ifdef __cplusplus
  const MojoCreateMessagePipeOptionsFlags
      MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE = 0;
  #else
  #define MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE \
    ((MojoCreateMessagePipeOptionsFlags)0)
  #endif
  
  MOJO_STATIC_ASSERT(MOJO_ALIGNOF(int64_t) == 8, "int64_t has weird alignment");
  struct MOJO_ALIGNAS(8) MojoCreateMessagePipeOptions {
    uint32_t struct_size;
    MojoCreateMessagePipeOptionsFlags flags;
  };
  MOJO_STATIC_ASSERT(sizeof(MojoCreateMessagePipeOptions) == 8,
                     "MojoCreateMessagePipeOptions has wrong size");
  
  // |MojoWriteMessageFlags|: Used to specify different modes to
  // |MojoWriteMessage()|.
  //   |MOJO_WRITE_MESSAGE_FLAG_NONE| - No flags; default mode.
  
  typedef uint32_t MojoWriteMessageFlags;
  
  #ifdef __cplusplus
  const MojoWriteMessageFlags MOJO_WRITE_MESSAGE_FLAG_NONE = 0;
  #else
  #define MOJO_WRITE_MESSAGE_FLAG_NONE ((MojoWriteMessageFlags)0)
  #endif
  
  // |MojoReadMessageFlags|: Used to specify different modes to
  // |MojoReadMessage()|.
  //   |MOJO_READ_MESSAGE_FLAG_NONE| - No flags; default mode.
  //   |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| - If the message is unable to be read
  //       for whatever reason (e.g., the caller-supplied buffer is too small),
  //       discard the message (i.e., simply dequeue it).
  
  typedef uint32_t MojoReadMessageFlags;
  
  #ifdef __cplusplus
  const MojoReadMessageFlags MOJO_READ_MESSAGE_FLAG_NONE = 0;
  const MojoReadMessageFlags MOJO_READ_MESSAGE_FLAG_MAY_DISCARD = 1 << 0;
  #else
  #define MOJO_READ_MESSAGE_FLAG_NONE ((MojoReadMessageFlags)0)
  #define MOJO_READ_MESSAGE_FLAG_MAY_DISCARD ((MojoReadMessageFlags)1 << 0)
  #endif
  
  // |MojoAllocMessageFlags|: Used to specify different options for
  // |MojoAllocMessage()|.
  //   |MOJO_ALLOC_MESSAGE_FLAG_NONE| - No flags; default mode.
  
  typedef uint32_t MojoAllocMessageFlags;
  
  #ifdef __cplusplus
  const MojoAllocMessageFlags MOJO_ALLOC_MESSAGE_FLAG_NONE = 0;
  #else
  #define MOJO_ALLOC_MESSAGE_FLAG_NONE ((MojoAllocMessageFlags)0)
  #endif
  
  #ifdef __cplusplus
  extern "C" {
  #endif
  
  // Note: See the comment in functions.h about the meaning of the "optional"
  // label for pointer parameters.
  
  // Creates a message pipe, which is a bidirectional communication channel for
  // framed data (i.e., messages). Messages can contain plain data and/or Mojo
  // handles.
  //
  // |options| may be set to null for a message pipe with the default options.
  //
  // On success, |*message_pipe_handle0| and |*message_pipe_handle1| are set to
  // handles for the two endpoints (ports) for the message pipe.
  //
  // Returns:
  //   |MOJO_RESULT_OK| on success.
  //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
  //       |*options| is invalid).
  //   |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has
  //       been reached.
  MOJO_SYSTEM_EXPORT MojoResult MojoCreateMessagePipe(
      const struct MojoCreateMessagePipeOptions* options,  // Optional.
      MojoHandle* message_pipe_handle0,                    // Out.
      MojoHandle* message_pipe_handle1);                   // Out.
  
  // Writes a message to the message pipe endpoint given by |message_pipe_handle|,
  // with message data specified by |bytes| of size |num_bytes| and attached
  // handles specified by |handles| of count |num_handles|, and options specified
  // by |flags|. If there is no message data, |bytes| may be null, in which case
  // |num_bytes| must be zero. If there are no attached handles, |handles| may be
  // null, in which case |num_handles| must be zero.
  //
  // If handles are attached, the handles will no longer be valid (on success the
  // receiver will receive equivalent, but logically different, handles). Handles
  // to be sent should not be in simultaneous use (e.g., on another thread).
  //
  // 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_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 some handle to be sent is currently in use.
  //
  // TODO(vtl): Add a notion of capacity for message pipes, and return
  // |MOJO_RESULT_SHOULD_WAIT| if the message pipe is full.
  MOJO_SYSTEM_EXPORT MojoResult
      MojoWriteMessage(MojoHandle message_pipe_handle,
                       const void* bytes,  // Optional.
                       uint32_t num_bytes,
                       const MojoHandle* handles,  // Optional.
                       uint32_t num_handles,
                       MojoWriteMessageFlags flags);
  
  // Writes a message to the message pipe endpoint given by |message_pipe_handle|.
  //
  // |message|: A message object allocated by |MojoAllocMessage()|. 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
  // the |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| flag was passed. At most one
  // message will be consumed from the queue, and the return value will indicate
  // whether a message was successfully read.
  //
  // |num_bytes| and |num_handles| are optional in/out parameters that on input
  // must be set to the sizes of the |bytes| and |handles| arrays, and on output
  // will be set to the actual number of bytes or handles contained in the
  // message (even if the message was not retrieved due to being too large).
  // Either |num_bytes| or |num_handles| may be null if the message is not
  // expected to contain the corresponding type of data, but such a call would
  // fail with |MOJO_RESULT_RESOURCE_EXHAUSTED| if the message in fact did
  // contain that type of data.
  //
  // |bytes| and |handles| will receive the contents of the message, if it is
  // retrieved. Either or both may be null, in which case the corresponding size
  // parameter(s) must also be set to zero or passed as null.
  //
  // Returns:
  //   |MOJO_RESULT_OK| on success (i.e., a message was actually read).
  //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid.
  //   |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed.
  //   |MOJO_RESULT_RESOURCE_EXHAUSTED| if the message was too large to fit in the
  //       provided buffer(s). The message will have been left in the queue or
  //       discarded, depending on flags.
  //   |MOJO_RESULT_SHOULD_WAIT| if no message was available to be read.
  //
  // TODO(vtl): Reconsider the |MOJO_RESULT_RESOURCE_EXHAUSTED| error code; should
  // distinguish this from the hitting-system-limits case.
  MOJO_SYSTEM_EXPORT MojoResult
      MojoReadMessage(MojoHandle message_pipe_handle,
                      void* bytes,            // Optional out.
                      uint32_t* num_bytes,    // Optional in/out.
                      MojoHandle* handles,    // Optional out.
                      uint32_t* num_handles,  // Optional in/out.
                      MojoReadMessageFlags flags);
  
  // Reads the next message from a message pipe and returns a message containing
  // the message bytes. The returned message must eventually be freed using
  // |MojoFreeMessage()|.
  //
  // 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 a handle to a message
  // object which may be passed to |MojoGetMessageBuffer()|. The caller owns the
  // message object and is responsible for freeing it via |MojoFreeMessage()|.
  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
  //
  // Fusing handle B and handle C results in a single pipe:
  //
  //     A <-> D
  //
  // Handles B and C are ALWAYS closed. Any unread messages at C will eventually
  // be delivered to A, and any unread messages at B will eventually be delivered
  // to D.
  //
  // NOTE: A handle may only be fused if it is an open message pipe handle which
  // has not been written to.
  //
  // Returns:
  //   |MOJO_RESULT_OK| on success.
  //   |MOJO_RESULT_FAILED_PRECONDITION| if both handles were valid message pipe
  //       handles but could not be merged (e.g. one of them has been written to).
  //   |MOJO_INVALID_ARGUMENT| if either handle is not a fusable message pipe
  //       handle.
  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 handle to be filled with the allocated message's
  //     handle. Must be non-null.
  //
  // Returns:
  //   |MOJO_RESULT_OK| if the message was successfully allocated. In this case
  //       |*message| will be populated with a handle to an allocated message
  //       with a buffer large enough to hold |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
  MojoAllocMessage(uint32_t num_bytes,
                   const MojoHandle* handles,
                   uint32_t num_handles,
                   MojoAllocMessageFlags flags,
                   MojoMessageHandle* message);  // Out
  
  // Frees a message allocated by |MojoAllocMessage()| or |MojoReadMessageNew()|.
  //
  // |message|: The message to free. This must correspond to a message previously
  //     allocated by |MojoAllocMessage()| or |MojoReadMessageNew()|. Note that if
  //     the message has already been passed to |MojoWriteMessageNew()| it should
  //     NOT also be freed with this API.
  //
  // Returns:
  //   |MOJO_RESULT_OK| if |message| was valid and has been freed.
  //   |MOJO_RESULT_INVALID_ARGUMENT| if |message| was not a valid message.
  MOJO_SYSTEM_EXPORT MojoResult MojoFreeMessage(MojoMessageHandle message);
  
  // Retrieves the address of mutable message bytes for a message allocated by
  // either |MojoAllocMessage()| or |MojoReadMessageNew()|.
  //
  // 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.
  //
  // NOTE: A returned buffer address is always guaranteed to be 8-byte aligned.
  MOJO_SYSTEM_EXPORT MojoResult MojoGetMessageBuffer(MojoMessageHandle message,
                                                     void** buffer);  // Out
  
  // Notifies the system that a bad message was received on a message pipe,
  // according to whatever criteria the caller chooses. This ultimately tries to
  // notify the embedder about the bad message, and the embedder may enforce some
  // policy for dealing with the source of the message (e.g. close the pipe,
  // terminate, a process, etc.) The embedder may not be notified if the calling
  // process has lost its connection to the source process.
  //
  // |message|: The message to report as bad. This must have come from a call to
  //     |MojoReadMessageNew()|.
  // |error|: An error string which may provide the embedder with context when
  //     notified of this error.
  // |error_num_bytes|: The length of |error| in bytes.
  //
  // Returns:
  //   |MOJO_RESULT_OK| if successful.
  //   |MOJO_RESULT_INVALID_ARGUMENT| if |message| is not a valid message.
  MOJO_SYSTEM_EXPORT MojoResult
  MojoNotifyBadMessage(MojoMessageHandle message,
                       const char* error,
                       size_t error_num_bytes);
  
  #ifdef __cplusplus
  }  // extern "C"
  #endif
  
  #endif  // MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_
  