OLD | NEW |
1 // Copyright 2014 The Chromium Authors. All rights reserved. | 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 | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 // This file contains types/constants and functions specific to message pipes. | 5 // This file contains types/constants and functions specific to message pipes. |
6 // | 6 // |
7 // Note: This header should be compilable as C. | 7 // Note: This header should be compilable as C. |
8 | 8 |
9 #ifndef MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_ | 9 #ifndef MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_ |
10 #define MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_ | 10 #define MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_ |
11 | 11 |
12 #include "mojo/public/c/system/macros.h" | 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" | 13 #include "mojo/public/c/system/types.h" |
15 | 14 |
16 // |MojoCreateMessagePipeOptions|: Used to specify creation parameters for a | 15 // |MojoCreateMessagePipeOptions|: Used to specify creation parameters for a |
17 // message pipe to |MojoCreateMessagePipe()|. | 16 // message pipe to |MojoCreateMessagePipe()|. |
18 // |uint32_t struct_size|: Set to the size of the | 17 // |uint32_t struct_size|: Set to the size of the |
19 // |MojoCreateMessagePipeOptions| struct. (Used to allow for future | 18 // |MojoCreateMessagePipeOptions| struct. (Used to allow for future |
20 // extensions.) | 19 // extensions.) |
21 // |MojoCreateMessagePipeOptionsFlags flags|: Reserved for future use. | 20 // |MojoCreateMessagePipeOptionsFlags flags|: Reserved for future use. |
22 // |MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE|: No flags; default mode. | 21 // |MOJO_CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE|: No flags; default mode. |
23 | 22 |
(...skipping 59 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
83 // | 82 // |
84 // On success, |*message_pipe_handle0| and |*message_pipe_handle1| are set to | 83 // On success, |*message_pipe_handle0| and |*message_pipe_handle1| are set to |
85 // handles for the two endpoints (ports) for the message pipe. | 84 // handles for the two endpoints (ports) for the message pipe. |
86 // | 85 // |
87 // Returns: | 86 // Returns: |
88 // |MOJO_RESULT_OK| on success. | 87 // |MOJO_RESULT_OK| on success. |
89 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., | 88 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., |
90 // |*options| is invalid). | 89 // |*options| is invalid). |
91 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has | 90 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has |
92 // been reached. | 91 // been reached. |
93 MOJO_SYSTEM_EXPORT MojoResult MojoCreateMessagePipe( | 92 MojoResult MojoCreateMessagePipe( |
94 const struct MojoCreateMessagePipeOptions* options, // Optional. | 93 const struct MojoCreateMessagePipeOptions* options, // Optional. |
95 MojoHandle* message_pipe_handle0, // Out. | 94 MojoHandle* message_pipe_handle0, // Out. |
96 MojoHandle* message_pipe_handle1); // Out. | 95 MojoHandle* message_pipe_handle1); // Out. |
97 | 96 |
98 // Writes a message to the message pipe endpoint given by |message_pipe_handle|, | 97 // Writes a message to the message pipe endpoint given by |message_pipe_handle|, |
99 // with message data specified by |bytes| of size |num_bytes| and attached | 98 // with message data specified by |bytes| of size |num_bytes| and attached |
100 // handles specified by |handles| of count |num_handles|, and options specified | 99 // handles specified by |handles| of count |num_handles|, and options specified |
101 // by |flags|. If there is no message data, |bytes| may be null, in which case | 100 // by |flags|. If there is no message data, |bytes| may be null, in which case |
102 // |num_bytes| must be zero. If there are no attached handles, |handles| may be | 101 // |num_bytes| must be zero. If there are no attached handles, |handles| may be |
103 // null, in which case |num_handles| must be zero. | 102 // null, in which case |num_handles| must be zero. |
(...skipping 12 matching lines...) Expand all Loading... |
116 // latter case). | 115 // latter case). |
117 // |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed. | 116 // |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed. |
118 // Note that closing an endpoint is not necessarily synchronous (e.g., | 117 // Note that closing an endpoint is not necessarily synchronous (e.g., |
119 // across processes), so this function may succeed even if the other | 118 // across processes), so this function may succeed even if the other |
120 // endpoint has been closed (in which case the message would be dropped). | 119 // endpoint has been closed (in which case the message would be dropped). |
121 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. | 120 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. |
122 // |MOJO_RESULT_BUSY| if some handle to be sent is currently in use. | 121 // |MOJO_RESULT_BUSY| if some handle to be sent is currently in use. |
123 // | 122 // |
124 // TODO(vtl): Add a notion of capacity for message pipes, and return | 123 // TODO(vtl): Add a notion of capacity for message pipes, and return |
125 // |MOJO_RESULT_SHOULD_WAIT| if the message pipe is full. | 124 // |MOJO_RESULT_SHOULD_WAIT| if the message pipe is full. |
126 MOJO_SYSTEM_EXPORT MojoResult | 125 MojoResult MojoWriteMessage(MojoHandle message_pipe_handle, |
127 MojoWriteMessage(MojoHandle message_pipe_handle, | 126 const void* bytes, // Optional. |
128 const void* bytes, // Optional. | 127 uint32_t num_bytes, |
129 uint32_t num_bytes, | 128 const MojoHandle* handles, // Optional. |
130 const MojoHandle* handles, // Optional. | 129 uint32_t num_handles, |
131 uint32_t num_handles, | 130 MojoWriteMessageFlags flags); |
132 MojoWriteMessageFlags flags); | |
133 | 131 |
134 // Reads the next message from a message pipe, or indicates the size of the | 132 // Reads the next message from a message pipe, or indicates the size of the |
135 // message if it cannot fit in the provided buffers. The message will be read | 133 // message if it cannot fit in the provided buffers. The message will be read |
136 // in its entirety or not at all; if it is not, it will remain enqueued unless | 134 // in its entirety or not at all; if it is not, it will remain enqueued unless |
137 // the |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| flag was passed. At most one | 135 // the |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| flag was passed. At most one |
138 // message will be consumed from the queue, and the return value will indicate | 136 // message will be consumed from the queue, and the return value will indicate |
139 // whether a message was successfully read. | 137 // whether a message was successfully read. |
140 // | 138 // |
141 // |num_bytes| and |num_handles| are optional in/out parameters that on input | 139 // |num_bytes| and |num_handles| are optional in/out parameters that on input |
142 // must be set to the sizes of the |bytes| and |handles| arrays, and on output | 140 // must be set to the sizes of the |bytes| and |handles| arrays, and on output |
(...skipping 12 matching lines...) Expand all Loading... |
155 // |MOJO_RESULT_OK| on success (i.e., a message was actually read). | 153 // |MOJO_RESULT_OK| on success (i.e., a message was actually read). |
156 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid. | 154 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid. |
157 // |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed. | 155 // |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed. |
158 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if the message was too large to fit in the | 156 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if the message was too large to fit in the |
159 // provided buffer(s). The message will have been left in the queue or | 157 // provided buffer(s). The message will have been left in the queue or |
160 // discarded, depending on flags. | 158 // discarded, depending on flags. |
161 // |MOJO_RESULT_SHOULD_WAIT| if no message was available to be read. | 159 // |MOJO_RESULT_SHOULD_WAIT| if no message was available to be read. |
162 // | 160 // |
163 // TODO(vtl): Reconsider the |MOJO_RESULT_RESOURCE_EXHAUSTED| error code; should | 161 // TODO(vtl): Reconsider the |MOJO_RESULT_RESOURCE_EXHAUSTED| error code; should |
164 // distinguish this from the hitting-system-limits case. | 162 // distinguish this from the hitting-system-limits case. |
165 MOJO_SYSTEM_EXPORT MojoResult | 163 MojoResult MojoReadMessage(MojoHandle message_pipe_handle, |
166 MojoReadMessage(MojoHandle message_pipe_handle, | 164 void* bytes, // Optional out. |
167 void* bytes, // Optional out. | 165 uint32_t* num_bytes, // Optional in/out. |
168 uint32_t* num_bytes, // Optional in/out. | 166 MojoHandle* handles, // Optional out. |
169 MojoHandle* handles, // Optional out. | 167 uint32_t* num_handles, // Optional in/out. |
170 uint32_t* num_handles, // Optional in/out. | 168 MojoReadMessageFlags flags); |
171 MojoReadMessageFlags flags); | |
172 | 169 |
173 #ifdef __cplusplus | 170 #ifdef __cplusplus |
174 } // extern "C" | 171 } // extern "C" |
175 #endif | 172 #endif |
176 | 173 |
177 #endif // MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_ | 174 #endif // MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_ |
OLD | NEW |