src/mojo/public/c/system/message_pipe.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // This file contains types/constants and functions specific to message pipes.
   6 //
   7 // Note: This header should be compilable as C.
   8
   9 #ifndef MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_
  10 #define MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_
  11
  12 #include "mojo/public/c/system/macros.h"
  13 #include "mojo/public/c/system/system_export.h"
  14 #include "mojo/public/c/system/types.h"
  15
  16 // |MojoCreateMessagePipeOptions|: Used to specify creation parameters for a
  17 // message pipe to |MojoCreateMessagePipe()|.
  18 //   |uint32_t struct_size|: Set to the size of the
  19 //       |MojoCreateMessagePipeOptions| struct. (Used to allow for future
  20 //       extensions.)
  21 //   |MojoCreateMessagePipeOptionsFlags flags|: Reserved for future use.
  22 //       |MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE|: No flags; default mode.
  23
  24 typedef uint32_t MojoCreateMessagePipeOptionsFlags;
  25
  26 #ifdef __cplusplus
  27 const MojoCreateMessagePipeOptionsFlags
  28     MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE = 0;
  29 #else
  30 #define MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE \
  31   ((MojoCreateMessagePipeOptionsFlags)0)
  32 #endif
  33
  34 MOJO_STATIC_ASSERT(MOJO_ALIGNOF(int64_t) == 8, "int64_t has weird alignment");
  35 struct MOJO_ALIGNAS(8) MojoCreateMessagePipeOptions {
  36   uint32_t struct_size;
  37   MojoCreateMessagePipeOptionsFlags flags;
  38 };
  39 MOJO_STATIC_ASSERT(sizeof(MojoCreateMessagePipeOptions) == 8,
  40                    "MojoCreateMessagePipeOptions has wrong size");
  41
  42 // |MojoWriteMessageFlags|: Used to specify different modes to
  43 // |MojoWriteMessage()|.
  44 //   |MOJO_WRITE_MESSAGE_FLAG_NONE| - No flags; default mode.
  45
  46 typedef uint32_t MojoWriteMessageFlags;
  47
  48 #ifdef __cplusplus
  49 const MojoWriteMessageFlags MOJO_WRITE_MESSAGE_FLAG_NONE = 0;
  50 #else
  51 #define MOJO_WRITE_MESSAGE_FLAG_NONE ((MojoWriteMessageFlags)0)
  52 #endif
  53
  54 // |MojoReadMessageFlags|: Used to specify different modes to
  55 // |MojoReadMessage()|.
  56 //   |MOJO_READ_MESSAGE_FLAG_NONE| - No flags; default mode.
  57 //   |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| - If the message is unable to be read
  58 //       for whatever reason (e.g., the caller-supplied buffer is too small),
  59 //       discard the message (i.e., simply dequeue it).
  60
  61 typedef uint32_t MojoReadMessageFlags;
  62
  63 #ifdef __cplusplus
  64 const MojoReadMessageFlags MOJO_READ_MESSAGE_FLAG_NONE = 0;
  65 const MojoReadMessageFlags MOJO_READ_MESSAGE_FLAG_MAY_DISCARD = 1 << 0;
  66 #else
  67 #define MOJO_READ_MESSAGE_FLAG_NONE ((MojoReadMessageFlags)0)
  68 #define MOJO_READ_MESSAGE_FLAG_MAY_DISCARD ((MojoReadMessageFlags)1 << 0)
  69 #endif
  70
  71 #ifdef __cplusplus
  72 extern "C" {
  73 #endif
  74
  75 // Note: See the comment in functions.h about the meaning of the "optional"
  76 // label for pointer parameters.
  77
  78 // Creates a message pipe, which is a bidirectional communication channel for
  79 // framed data (i.e., messages). Messages can contain plain data and/or Mojo
  80 // handles.
  81 //
  82 // |options| may be set to null for a message pipe with the default options.
  83 //
  84 // On success, |*message_pipe_handle0| and |*message_pipe_handle1| are set to
  85 // handles for the two endpoints (ports) for the message pipe.
  86 //
  87 // Returns:
  88 //   |MOJO_RESULT_OK| on success.
  89 //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
  90 //       |*options| is invalid).
  91 //   |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has
  92 //       been reached.
  93 //
  94 // TODO(vtl): Add an options struct pointer argument.
  95 MOJO_SYSTEM_EXPORT MojoResult MojoCreateMessagePipe(
  96     const struct MojoCreateMessagePipeOptions* options,  // Optional.
  97     MojoHandle* message_pipe_handle0,                    // Out.
  98     MojoHandle* message_pipe_handle1);                   // Out.
  99
 100 // Writes a message to the message pipe endpoint given by |message_pipe_handle|,
 101 // with message data specified by |bytes| of size |num_bytes| and attached
 102 // handles specified by |handles| of count |num_handles|, and options specified
 103 // by |flags|. If there is no message data, |bytes| may be null, in which case
 104 // |num_bytes| must be zero. If there are no attached handles, |handles| may be
 105 // null, in which case |num_handles| must be zero.
 106 //
 107 // If handles are attached, on success the handles will no longer be valid (the
 108 // receiver will receive equivalent, but logically different, handles). Handles
 109 // to be sent should not be in simultaneous use (e.g., on another thread).
 110 //
 111 // Returns:
 112 //   |MOJO_RESULT_OK| on success (i.e., the message was enqueued).
 113 //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if
 114 //       |message_pipe_handle| is not a valid handle, or some of the
 115 //       requirements above are not satisfied).
 116 //   |MOJO_RESULT_RESOURCE_EXHAUSTED| if some system limit has been reached, or
 117 //       the number of handles to send is too large (TODO(vtl): reconsider the
 118 //       latter case).
 119 //   |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed.
 120 //       Note that closing an endpoint is not necessarily synchronous (e.g.,
 121 //       across processes), so this function may be succeed even if the other
 122 //       endpoint has been closed (in which case the message would be dropped).
 123 //   |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|.
 124 //   |MOJO_RESULT_BUSY| if some handle to be sent is currently in use.
 125 //
 126 // TODO(vtl): Add a notion of capacity for message pipes, and return
 127 // |MOJO_RESULT_SHOULD_WAIT| if the message pipe is full.
 128 MOJO_SYSTEM_EXPORT MojoResult
 129     MojoWriteMessage(MojoHandle message_pipe_handle,
 130                      const void* bytes,  // Optional.
 131                      uint32_t num_bytes,
 132                      const MojoHandle* handles,  // Optional.
 133                      uint32_t num_handles,
 134                      MojoWriteMessageFlags flags);
 135
 136 // Reads a message from the message pipe endpoint given by
 137 // |message_pipe_handle|; also usable to query the size of the next message or
 138 // discard the next message. |bytes|/|*num_bytes| indicate the buffer/buffer
 139 // size to receive the message data (if any) and |handles|/|*num_handles|
 140 // indicate the buffer/maximum handle count to receive the attached handles (if
 141 // any).
 142 //
 143 // |num_bytes| and |num_handles| are optional "in-out" parameters. If non-null,
 144 // on return |*num_bytes| and |*num_handles| will usually indicate the number
 145 // of bytes and number of attached handles in the "next" message, respectively,
 146 // whether that message was read or not. (If null, the number of bytes/handles
 147 // is treated as zero.)
 148 //
 149 // If |bytes| is null, then |*num_bytes| must be zero, and similarly for
 150 // |handles| and |*num_handles|.
 151 //
 152 // Partial reads are NEVER done. Either a full read is done and |MOJO_RESULT_OK|
 153 // returned, or the read is NOT done and |MOJO_RESULT_RESOURCE_EXHAUSTED| is
 154 // returned (if |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| was set, the message is
 155 // also discarded in this case).
 156 //
 157 // Returns:
 158 //   |MOJO_RESULT_OK| on success (i.e., a message was actually read).
 159 //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid.
 160 //   |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed.
 161 //   |MOJO_RESULT_RESOURCE_EXHAUSTED| if one of the buffers to receive the
 162 //       message/attached handles (|bytes|/|*num_bytes| or
 163 //       |handles|/|*num_handles|) was too small. (TODO(vtl): Reconsider this
 164 //       error code; should distinguish this from the hitting-system-limits
 165 //       case.)
 166 //   |MOJO_RESULT_SHOULD_WAIT| if no message was available to be read.
 167 MOJO_SYSTEM_EXPORT MojoResult
 168     MojoReadMessage(MojoHandle message_pipe_handle,
 169                     void* bytes,            // Optional out.
 170                     uint32_t* num_bytes,    // Optional in/out.
 171                     MojoHandle* handles,    // Optional out.
 172                     uint32_t* num_handles,  // Optional in/out.
 173                     MojoReadMessageFlags flags);
 174
 175 #ifdef __cplusplus
 176 }  // extern "C"
 177 #endif
 178
 179 #endif  // MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_