| OLD | NEW |
|---|
| (Empty) |
| 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_ | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 814543006:
Move //mojo/{public, edk} underneath //third_party (Closed)
Base URL: https://chromium.googlesource.com/chromium/src.git@master