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 data pipes. | 5 // This file contains types/constants and functions specific to data 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_DATA_PIPE_H_ | 9 #ifndef MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_ |
10 #define MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_ | 10 #define MOJO_PUBLIC_C_SYSTEM_DATA_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 // |MojoCreateDataPipeOptions|: Used to specify creation parameters for a data | 15 // |MojoCreateDataPipeOptions|: Used to specify creation parameters for a data |
17 // pipe to |MojoCreateDataPipe()|. | 16 // pipe to |MojoCreateDataPipe()|. |
18 // |uint32_t struct_size|: Set to the size of the |MojoCreateDataPipeOptions| | 17 // |uint32_t struct_size|: Set to the size of the |MojoCreateDataPipeOptions| |
19 // struct. (Used to allow for future extensions.) | 18 // struct. (Used to allow for future extensions.) |
20 // |MojoCreateDataPipeOptionsFlags flags|: Used to specify different modes of | 19 // |MojoCreateDataPipeOptionsFlags flags|: Used to specify different modes of |
21 // operation. | 20 // operation. |
22 // |MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_NONE|: No flags; default mode. | 21 // |MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_NONE|: No flags; default mode. |
23 // |uint32_t element_num_bytes|: The size of an element, in bytes. All | 22 // |uint32_t element_num_bytes|: The size of an element, in bytes. All |
(...skipping 94 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
118 // consumer. (On failure, they are not modified.) | 117 // consumer. (On failure, they are not modified.) |
119 // | 118 // |
120 // Returns: | 119 // Returns: |
121 // |MOJO_RESULT_OK| on success. | 120 // |MOJO_RESULT_OK| on success. |
122 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., | 121 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., |
123 // |*options| is invalid). | 122 // |*options| is invalid). |
124 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has | 123 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has |
125 // been reached (e.g., if the requested capacity was too large, or if the | 124 // been reached (e.g., if the requested capacity was too large, or if the |
126 // maximum number of handles was exceeded). | 125 // maximum number of handles was exceeded). |
127 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. | 126 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. |
128 MOJO_SYSTEM_EXPORT MojoResult MojoCreateDataPipe( | 127 MojoResult MojoCreateDataPipe( |
129 const struct MojoCreateDataPipeOptions* options, // Optional. | 128 const struct MojoCreateDataPipeOptions* options, // Optional. |
130 MojoHandle* data_pipe_producer_handle, // Out. | 129 MojoHandle* data_pipe_producer_handle, // Out. |
131 MojoHandle* data_pipe_consumer_handle); // Out. | 130 MojoHandle* data_pipe_consumer_handle); // Out. |
132 | 131 |
133 // Writes the given data to the data pipe producer given by | 132 // Writes the given data to the data pipe producer given by |
134 // |data_pipe_producer_handle|. |elements| points to data of size |*num_bytes|; | 133 // |data_pipe_producer_handle|. |elements| points to data of size |*num_bytes|; |
135 // |*num_bytes| should be a multiple of the data pipe's element size. If | 134 // |*num_bytes| should be a multiple of the data pipe's element size. If |
136 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| is set in |flags|, either all the data | 135 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| is set in |flags|, either all the data |
137 // will be written or none is. | 136 // will be written or none is. |
138 // | 137 // |
(...skipping 12 matching lines...) Expand all Loading... |
151 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set and the required amount of data | 150 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set and the required amount of data |
152 // (specified by |*num_bytes|) could not be written. | 151 // (specified by |*num_bytes|) could not be written. |
153 // |MOJO_RESULT_BUSY| if there is a two-phase write ongoing with | 152 // |MOJO_RESULT_BUSY| if there is a two-phase write ongoing with |
154 // |data_pipe_producer_handle| (i.e., |MojoBeginWriteData()| has been | 153 // |data_pipe_producer_handle| (i.e., |MojoBeginWriteData()| has been |
155 // called, but not yet the matching |MojoEndWriteData()|). | 154 // called, but not yet the matching |MojoEndWriteData()|). |
156 // |MOJO_RESULT_SHOULD_WAIT| if no data can currently be written (and the | 155 // |MOJO_RESULT_SHOULD_WAIT| if no data can currently be written (and the |
157 // consumer is still open) and |flags| does *not* have | 156 // consumer is still open) and |flags| does *not* have |
158 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set. | 157 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set. |
159 // | 158 // |
160 // TODO(vtl): Should there be a way of querying how much data can be written? | 159 // TODO(vtl): Should there be a way of querying how much data can be written? |
161 MOJO_SYSTEM_EXPORT MojoResult | 160 MojoResult MojoWriteData(MojoHandle data_pipe_producer_handle, |
162 MojoWriteData(MojoHandle data_pipe_producer_handle, | 161 const void* elements, |
163 const void* elements, | 162 uint32_t* num_bytes, // In/out. |
164 uint32_t* num_bytes, // In/out. | 163 MojoWriteDataFlags flags); |
165 MojoWriteDataFlags flags); | |
166 | 164 |
167 // Begins a two-phase write to the data pipe producer given by | 165 // Begins a two-phase write to the data pipe producer given by |
168 // |data_pipe_producer_handle|. On success, |*buffer| will be a pointer to which | 166 // |data_pipe_producer_handle|. On success, |*buffer| will be a pointer to which |
169 // the caller can write |*buffer_num_bytes| bytes of data. There are currently | 167 // the caller can write |*buffer_num_bytes| bytes of data. There are currently |
170 // no flags allowed, so |flags| should be |MOJO_WRITE_DATA_FLAG_NONE|. | 168 // no flags allowed, so |flags| should be |MOJO_WRITE_DATA_FLAG_NONE|. |
171 // | 169 // |
172 // During a two-phase write, |data_pipe_producer_handle| is *not* writable. | 170 // During a two-phase write, |data_pipe_producer_handle| is *not* writable. |
173 // E.g., if another thread tries to write to it, it will get |MOJO_RESULT_BUSY|; | 171 // E.g., if another thread tries to write to it, it will get |MOJO_RESULT_BUSY|; |
174 // that thread can then wait for |data_pipe_producer_handle| to become writable | 172 // that thread can then wait for |data_pipe_producer_handle| to become writable |
175 // again. | 173 // again. |
176 // | 174 // |
177 // When |MojoBeginWriteData()| returns |MOJO_RESULT_OK|, and the caller has | 175 // When |MojoBeginWriteData()| returns |MOJO_RESULT_OK|, and the caller has |
178 // finished writing data to |*buffer|, it should call |MojoEndWriteData()| to | 176 // finished writing data to |*buffer|, it should call |MojoEndWriteData()| to |
179 // specify the amount written and to complete the two-phase write. | 177 // specify the amount written and to complete the two-phase write. |
180 // |MojoEndWriteData()| need not be called for other return values. | 178 // |MojoEndWriteData()| need not be called for other return values. |
181 // | 179 // |
182 // Returns: | 180 // Returns: |
183 // |MOJO_RESULT_OK| on success. | 181 // |MOJO_RESULT_OK| on success. |
184 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., | 182 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., |
185 // |data_pipe_producer_handle| is not a handle to a data pipe producer or | 183 // |data_pipe_producer_handle| is not a handle to a data pipe producer or |
186 // flags has |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set). | 184 // flags has |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set). |
187 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer handle has been | 185 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer handle has been |
188 // closed. | 186 // closed. |
189 // |MOJO_RESULT_BUSY| if there is already a two-phase write ongoing with | 187 // |MOJO_RESULT_BUSY| if there is already a two-phase write ongoing with |
190 // |data_pipe_producer_handle| (i.e., |MojoBeginWriteData()| has been | 188 // |data_pipe_producer_handle| (i.e., |MojoBeginWriteData()| has been |
191 // called, but not yet the matching |MojoEndWriteData()|). | 189 // called, but not yet the matching |MojoEndWriteData()|). |
192 // |MOJO_RESULT_SHOULD_WAIT| if no data can currently be written (and the | 190 // |MOJO_RESULT_SHOULD_WAIT| if no data can currently be written (and the |
193 // consumer is still open). | 191 // consumer is still open). |
194 MOJO_SYSTEM_EXPORT MojoResult | 192 MojoResult MojoBeginWriteData(MojoHandle data_pipe_producer_handle, |
195 MojoBeginWriteData(MojoHandle data_pipe_producer_handle, | 193 void** buffer, // Out. |
196 void** buffer, // Out. | 194 uint32_t* buffer_num_bytes, // Out. |
197 uint32_t* buffer_num_bytes, // Out. | 195 MojoWriteDataFlags flags); |
198 MojoWriteDataFlags flags); | |
199 | 196 |
200 // Ends a two-phase write to the data pipe producer given by | 197 // Ends a two-phase write to the data pipe producer given by |
201 // |data_pipe_producer_handle| that was begun by a call to | 198 // |data_pipe_producer_handle| that was begun by a call to |
202 // |MojoBeginWriteData()| on the same handle. |num_bytes_written| should | 199 // |MojoBeginWriteData()| on the same handle. |num_bytes_written| should |
203 // indicate the amount of data actually written; it must be less than or equal | 200 // indicate the amount of data actually written; it must be less than or equal |
204 // to the value of |*buffer_num_bytes| output by |MojoBeginWriteData()| and must | 201 // to the value of |*buffer_num_bytes| output by |MojoBeginWriteData()| and must |
205 // be a multiple of the element size. The buffer given by |*buffer| from | 202 // be a multiple of the element size. The buffer given by |*buffer| from |
206 // |MojoBeginWriteData()| must have been filled with exactly |num_bytes_written| | 203 // |MojoBeginWriteData()| must have been filled with exactly |num_bytes_written| |
207 // bytes of data. | 204 // bytes of data. |
208 // | 205 // |
209 // On failure, the two-phase write (if any) is ended (so the handle may become | 206 // On failure, the two-phase write (if any) is ended (so the handle may become |
210 // writable again, if there's space available) but no data written to |*buffer| | 207 // writable again, if there's space available) but no data written to |*buffer| |
211 // is "put into" the data pipe. | 208 // is "put into" the data pipe. |
212 // | 209 // |
213 // Returns: | 210 // Returns: |
214 // |MOJO_RESULT_OK| on success. | 211 // |MOJO_RESULT_OK| on success. |
215 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., | 212 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., |
216 // |data_pipe_producer_handle| is not a handle to a data pipe producer or | 213 // |data_pipe_producer_handle| is not a handle to a data pipe producer or |
217 // |num_bytes_written| is invalid (greater than the maximum value provided | 214 // |num_bytes_written| is invalid (greater than the maximum value provided |
218 // by |MojoBeginWriteData()| or not a multiple of the element size). | 215 // by |MojoBeginWriteData()| or not a multiple of the element size). |
219 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer is not in a | 216 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer is not in a |
220 // two-phase write (e.g., |MojoBeginWriteData()| was not called or | 217 // two-phase write (e.g., |MojoBeginWriteData()| was not called or |
221 // |MojoEndWriteData()| has already been called). | 218 // |MojoEndWriteData()| has already been called). |
222 MOJO_SYSTEM_EXPORT MojoResult | 219 MojoResult MojoEndWriteData(MojoHandle data_pipe_producer_handle, |
223 MojoEndWriteData(MojoHandle data_pipe_producer_handle, | 220 uint32_t num_bytes_written); |
224 uint32_t num_bytes_written); | |
225 | 221 |
226 // Reads data from the data pipe consumer given by |data_pipe_consumer_handle|. | 222 // Reads data from the data pipe consumer given by |data_pipe_consumer_handle|. |
227 // May also be used to discard data or query the amount of data available. | 223 // May also be used to discard data or query the amount of data available. |
228 // | 224 // |
229 // If |flags| has neither |MOJO_READ_DATA_FLAG_DISCARD| nor | 225 // If |flags| has neither |MOJO_READ_DATA_FLAG_DISCARD| nor |
230 // |MOJO_READ_DATA_FLAG_QUERY| set, this tries to read up to |*num_bytes| (which | 226 // |MOJO_READ_DATA_FLAG_QUERY| set, this tries to read up to |*num_bytes| (which |
231 // must be a multiple of the data pipe's element size) bytes of data to | 227 // must be a multiple of the data pipe's element size) bytes of data to |
232 // |elements| and set |*num_bytes| to the amount actually read. If flags has | 228 // |elements| and set |*num_bytes| to the amount actually read. If flags has |
233 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set, it will either read exactly | 229 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set, it will either read exactly |
234 // |*num_bytes| bytes of data or none. Additionally, if flags has | 230 // |*num_bytes| bytes of data or none. Additionally, if flags has |
(...skipping 25 matching lines...) Expand all Loading... |
260 // be read or discarded. | 256 // be read or discarded. |
261 // |MOJO_RESULT_OUT_OF_RANGE| if |flags| has |MOJO_READ_DATA_FLAG_ALL_OR_NONE| | 257 // |MOJO_RESULT_OUT_OF_RANGE| if |flags| has |MOJO_READ_DATA_FLAG_ALL_OR_NONE| |
262 // set and the required amount of data is not available to be read or | 258 // set and the required amount of data is not available to be read or |
263 // discarded (and the producer is still open). | 259 // discarded (and the producer is still open). |
264 // |MOJO_RESULT_BUSY| if there is a two-phase read ongoing with | 260 // |MOJO_RESULT_BUSY| if there is a two-phase read ongoing with |
265 // |data_pipe_consumer_handle| (i.e., |MojoBeginReadData()| has been | 261 // |data_pipe_consumer_handle| (i.e., |MojoBeginReadData()| has been |
266 // called, but not yet the matching |MojoEndReadData()|). | 262 // called, but not yet the matching |MojoEndReadData()|). |
267 // |MOJO_RESULT_SHOULD_WAIT| if there is no data to be read or discarded (and | 263 // |MOJO_RESULT_SHOULD_WAIT| if there is no data to be read or discarded (and |
268 // the producer is still open) and |flags| does *not* have | 264 // the producer is still open) and |flags| does *not* have |
269 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set. | 265 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set. |
270 MOJO_SYSTEM_EXPORT MojoResult MojoReadData(MojoHandle data_pipe_consumer_handle, | 266 MojoResult MojoReadData(MojoHandle data_pipe_consumer_handle, |
271 void* elements, // Out. | 267 void* elements, // Out. |
272 uint32_t* num_bytes, // In/out. | 268 uint32_t* num_bytes, // In/out. |
273 MojoReadDataFlags flags); | 269 MojoReadDataFlags flags); |
274 | 270 |
275 // Begins a two-phase read from the data pipe consumer given by | 271 // Begins a two-phase read from the data pipe consumer given by |
276 // |data_pipe_consumer_handle|. On success, |*buffer| will be a pointer from | 272 // |data_pipe_consumer_handle|. On success, |*buffer| will be a pointer from |
277 // which the caller can read |*buffer_num_bytes| bytes of data. There are | 273 // which the caller can read |*buffer_num_bytes| bytes of data. There are |
278 // currently no valid flags, so |flags| must be |MOJO_READ_DATA_FLAG_NONE|. | 274 // currently no valid flags, so |flags| must be |MOJO_READ_DATA_FLAG_NONE|. |
279 // | 275 // |
280 // During a two-phase read, |data_pipe_consumer_handle| is *not* readable. | 276 // During a two-phase read, |data_pipe_consumer_handle| is *not* readable. |
281 // E.g., if another thread tries to read from it, it will get | 277 // E.g., if another thread tries to read from it, it will get |
282 // |MOJO_RESULT_BUSY|; that thread can then wait for |data_pipe_consumer_handle| | 278 // |MOJO_RESULT_BUSY|; that thread can then wait for |data_pipe_consumer_handle| |
283 // to become readable again. | 279 // to become readable again. |
284 // | 280 // |
285 // Once the caller has finished reading data from |*buffer|, it should call | 281 // Once the caller has finished reading data from |*buffer|, it should call |
286 // |MojoEndReadData()| to specify the amount read and to complete the two-phase | 282 // |MojoEndReadData()| to specify the amount read and to complete the two-phase |
287 // read. | 283 // read. |
288 // | 284 // |
289 // Returns: | 285 // Returns: |
290 // |MOJO_RESULT_OK| on success. | 286 // |MOJO_RESULT_OK| on success. |
291 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., | 287 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., |
292 // |data_pipe_consumer_handle| is not a handle to a data pipe consumer, | 288 // |data_pipe_consumer_handle| is not a handle to a data pipe consumer, |
293 // or |flags| has invalid flags set). | 289 // or |flags| has invalid flags set). |
294 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer handle has been | 290 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer handle has been |
295 // closed. | 291 // closed. |
296 // |MOJO_RESULT_BUSY| if there is already a two-phase read ongoing with | 292 // |MOJO_RESULT_BUSY| if there is already a two-phase read ongoing with |
297 // |data_pipe_consumer_handle| (i.e., |MojoBeginReadData()| has been | 293 // |data_pipe_consumer_handle| (i.e., |MojoBeginReadData()| has been |
298 // called, but not yet the matching |MojoEndReadData()|). | 294 // called, but not yet the matching |MojoEndReadData()|). |
299 // |MOJO_RESULT_SHOULD_WAIT| if no data can currently be read (and the | 295 // |MOJO_RESULT_SHOULD_WAIT| if no data can currently be read (and the |
300 // producer is still open). | 296 // producer is still open). |
301 MOJO_SYSTEM_EXPORT MojoResult | 297 MojoResult MojoBeginReadData(MojoHandle data_pipe_consumer_handle, |
302 MojoBeginReadData(MojoHandle data_pipe_consumer_handle, | 298 const void** buffer, // Out. |
303 const void** buffer, // Out. | 299 uint32_t* buffer_num_bytes, // Out. |
304 uint32_t* buffer_num_bytes, // Out. | 300 MojoReadDataFlags flags); |
305 MojoReadDataFlags flags); | |
306 | 301 |
307 // Ends a two-phase read from the data pipe consumer given by | 302 // Ends a two-phase read from the data pipe consumer given by |
308 // |data_pipe_consumer_handle| that was begun by a call to |MojoBeginReadData()| | 303 // |data_pipe_consumer_handle| that was begun by a call to |MojoBeginReadData()| |
309 // on the same handle. |num_bytes_read| should indicate the amount of data | 304 // on the same handle. |num_bytes_read| should indicate the amount of data |
310 // actually read; it must be less than or equal to the value of | 305 // actually read; it must be less than or equal to the value of |
311 // |*buffer_num_bytes| output by |MojoBeginReadData()| and must be a multiple of | 306 // |*buffer_num_bytes| output by |MojoBeginReadData()| and must be a multiple of |
312 // the element size. | 307 // the element size. |
313 // | 308 // |
314 // On failure, the two-phase read (if any) is ended (so the handle may become | 309 // On failure, the two-phase read (if any) is ended (so the handle may become |
315 // readable again) but no data is "removed" from the data pipe. | 310 // readable again) but no data is "removed" from the data pipe. |
316 // | 311 // |
317 // Returns: | 312 // Returns: |
318 // |MOJO_RESULT_OK| on success. | 313 // |MOJO_RESULT_OK| on success. |
319 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., | 314 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., |
320 // |data_pipe_consumer_handle| is not a handle to a data pipe consumer or | 315 // |data_pipe_consumer_handle| is not a handle to a data pipe consumer or |
321 // |num_bytes_written| is greater than the maximum value provided by | 316 // |num_bytes_written| is greater than the maximum value provided by |
322 // |MojoBeginReadData()| or not a multiple of the element size). | 317 // |MojoBeginReadData()| or not a multiple of the element size). |
323 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer is not in a | 318 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer is not in a |
324 // two-phase read (e.g., |MojoBeginReadData()| was not called or | 319 // two-phase read (e.g., |MojoBeginReadData()| was not called or |
325 // |MojoEndReadData()| has already been called). | 320 // |MojoEndReadData()| has already been called). |
326 MOJO_SYSTEM_EXPORT MojoResult | 321 MojoResult MojoEndReadData(MojoHandle data_pipe_consumer_handle, |
327 MojoEndReadData(MojoHandle data_pipe_consumer_handle, uint32_t num_bytes_read); | 322 uint32_t num_bytes_read); |
328 | 323 |
329 #ifdef __cplusplus | 324 #ifdef __cplusplus |
330 } // extern "C" | 325 } // extern "C" |
331 #endif | 326 #endif |
332 | 327 |
333 #endif // MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_ | 328 #endif // MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_ |
OLD | NEW |