1/* Copyright (c) 2012 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
6
7/**
8 * This file defines the API to create a file i/o object.
9 */
10
11[generate_thunk]
12
13label Chrome {
14  M14 = 1.0,
15  M25 = 1.1,
16  M29 = 1.2
17};
18
19/**
20 * The PP_FileOpenFlags enum contains file open constants.
21 */
22[assert_size(4)]
23 enum PP_FileOpenFlags {
24  /** Requests read access to a file. */
25  PP_FILEOPENFLAG_READ      = 1 << 0,
26
27  /**
28   * Requests write access to a file.  May be combined with
29   * <code>PP_FILEOPENFLAG_READ</code> to request read and write access.
30   */
31  PP_FILEOPENFLAG_WRITE     = 1 << 1,
32
33  /**
34   * Requests that the file be created if it does not exist.  If the file
35   * already exists, then this flag is ignored unless
36   * <code>PP_FILEOPENFLAG_EXCLUSIVE</code> was also specified, in which case
37   * FileIO::Open() will fail.
38   */
39  PP_FILEOPENFLAG_CREATE    = 1 << 2,
40
41  /**
42   * Requests that the file be truncated to length 0 if it exists and is a
43   * regular file. <code>PP_FILEOPENFLAG_WRITE</code> must also be specified.
44   */
45  PP_FILEOPENFLAG_TRUNCATE  = 1 << 3,
46
47  /**
48   * Requests that the file is created when this flag is combined with
49   * <code>PP_FILEOPENFLAG_CREATE</code>.  If this flag is specified, and the
50   * file already exists, then the FileIO::Open() call will fail.
51   */
52  PP_FILEOPENFLAG_EXCLUSIVE = 1 << 4,
53
54 /**
55  * Requests write access to a file, but writes will always occur at the end of
56  * the file. Mututally exclusive with <code>PP_FILEOPENFLAG_WRITE</code>.
57  *
58  * This is only supported in version 1.2 (Chrome 29) and later.
59  */
60  [version=1.2]
61  PP_FILEOPENFLAG_APPEND = 1 << 5
62};
63
64
65/**
66 * The <code>PPB_FileIO</code> struct is used to operate on a regular file
67 * (PP_FileType_Regular).
68 */
69interface PPB_FileIO {
70  /**
71   * Create() creates a new FileIO object.
72   *
73   * @param[in] instance A <code>PP_Instance</code> identifying the instance
74   * with the file.
75   *
76   * @return A <code>PP_Resource</code> corresponding to a FileIO if
77   * successful or 0 if the module is invalid.
78   */
79  PP_Resource Create([in] PP_Instance instance);
80  /**
81   * IsFileIO() determines if the provided resource is a FileIO.
82   *
83   * @param[in] resource A <code>PP_Resource</code> corresponding to a FileIO.
84   *
85   * @return <code>PP_TRUE</code> if the resource is a
86   * <code>PPB_FileIO</code>, <code>PP_FALSE</code> if the resource is
87   * invalid or some type other than <code>PPB_FileIO</code>.
88   */
89  PP_Bool IsFileIO([in] PP_Resource resource);
90
91  /**
92   * Open() opens the specified regular file for I/O according to the given
93   * open flags, which is a bit-mask of the <code>PP_FileOpenFlags</code>
94   * values. Upon success, the corresponding file is classified as "in use"
95   * by this FileIO object until such time as the FileIO object is closed
96   * or destroyed.
97   *
98   * @param[in] file_io A <code>PP_Resource</code> corresponding to a
99   * FileIO.
100   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
101   * reference.
102   * @param[in] open_flags A bit-mask of the <code>PP_FileOpenFlags</code>
103   * values.
104   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
105   * completion of Open().
106   *
107   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
108   */
109  int32_t Open([in] PP_Resource file_io,
110               [in] PP_Resource file_ref,
111               [in] int32_t open_flags,
112               [in] PP_CompletionCallback callback);
113
114  /**
115   * Query() queries info about the file opened by this FileIO object. The
116   * FileIO object must be opened, and there must be no other operations
117   * pending.
118   *
119   * @param[in] file_io A <code>PP_Resource</code> corresponding to a
120   * FileIO.
121   * @param[out] info The <code>PP_FileInfo</code> structure representing all
122   * information about the file.
123   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
124   * completion of Query(). <code>info</code> must remain valid until after the
125   * callback runs. If you pass a blocking callback, <code>info</code> must
126   * remain valid until after Query() returns.
127   *
128   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
129   * PP_ERROR_FAILED will be returned if the file isn't opened, and
130   * PP_ERROR_INPROGRESS will be returned if there is another operation pending.
131   */
132  int32_t Query([in] PP_Resource file_io,
133                [out] PP_FileInfo info,
134                [in] PP_CompletionCallback callback);
135
136  /**
137   * Touch() Updates time stamps for the file opened by this FileIO object.
138   * This function will fail if the FileIO object has not been opened. The
139   * FileIO object must be opened, and there must be no other operations
140   * pending.
141   *
142   * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
143   * FileIO.
144   * @param[in] last_access_time The last time the FileIO was accessed.
145   * @param[in] last_modified_time The last time the FileIO was modified.
146   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
147   * completion of Touch().
148   *
149   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
150   * PP_ERROR_FAILED will be returned if the file isn't opened, and
151   * PP_ERROR_INPROGRESS will be returned if there is another operation pending.
152   */
153  int32_t Touch([in] PP_Resource file_io,
154                [in] PP_Time last_access_time,
155                [in] PP_Time last_modified_time,
156                [in] PP_CompletionCallback callback);
157
158  /**
159   * Read() reads from an offset in the file.  The size of the buffer must be
160   * large enough to hold the specified number of bytes to read.  This function
161   * might perform a partial read, meaning all the requested bytes
162   * might not be returned, even if the end of the file has not been reached.
163   * The FileIO object must have been opened with read access.
164   *
165   * ReadToArray() is preferred to Read() when doing asynchronous operations.
166   *
167   * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
168   * FileIO.
169   * @param[in] offset The offset into the file.
170   * @param[in] buffer The buffer to hold the specified number of bytes read.
171   * @param[in] bytes_to_read The number of bytes to read from
172   * <code>offset</code>.
173   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
174   * completion of Read(). <code>buffer</code> must remain valid until after
175   * the callback runs. If you pass a blocking callback, <code>buffer</code>
176   * must remain valid until after Read() returns.
177   *
178   * @return The number of bytes read or an error code from
179   * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was
180   * reached. It is valid to call Read() multiple times with a completion
181   * callback to queue up parallel reads from the file, but pending reads
182   * cannot be interleaved with other operations.
183   */
184  int32_t Read([in] PP_Resource file_io,
185               [in] int64_t offset,
186               [inout] str_t buffer,
187               [in] int32_t bytes_to_read,
188               [in] PP_CompletionCallback callback);
189
190  /**
191   * Write() writes to an offset in the file.  This function might perform a
192   * partial write. The FileIO object must have been opened with write access.
193   *
194   * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
195   * FileIO.
196   * @param[in] offset The offset into the file.
197   * @param[in] buffer The buffer to hold the specified number of bytes read.
198   * @param[in] bytes_to_write The number of bytes to write to
199   * <code>offset</code>.
200   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
201   * completion of Write().
202   *
203   * @return The number of bytes written or an error code from
204   * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was
205   * reached. It is valid to call Write() multiple times with a completion
206   * callback to queue up parallel writes to the file, but pending writes
207   * cannot be interleaved with other operations.
208   */
209  int32_t Write([in] PP_Resource file_io,
210                [in] int64_t offset,
211                [in] str_t buffer,
212                [in] int32_t bytes_to_write,
213                [in] PP_CompletionCallback callback);
214  /**
215   * SetLength() sets the length of the file.  If the file size is extended,
216   * then the extended area of the file is zero-filled. The FileIO object must
217   * have been opened with write access and there must be no other operations
218   * pending.
219   *
220   * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
221   * FileIO.
222   * @param[in] length The length of the file to be set.
223   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
224   * completion of SetLength().
225   *
226   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
227   * PP_ERROR_FAILED will be returned if the file isn't opened, and
228   * PP_ERROR_INPROGRESS will be returned if there is another operation pending.
229   */
230  int32_t SetLength([in] PP_Resource file_io,
231                    [in] int64_t length,
232                    [in] PP_CompletionCallback callback);
233
234  /**
235   * Flush() flushes changes to disk.  This call can be very expensive! The
236   * FileIO object must have been opened with write access and there must be no
237   * other operations pending.
238   *
239   * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
240   * FileIO.
241   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
242   * completion of Flush().
243   *
244   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
245   * PP_ERROR_FAILED will be returned if the file isn't opened, and
246   * PP_ERROR_INPROGRESS will be returned if there is another operation pending.
247   */
248  int32_t Flush([in] PP_Resource file_io,
249                [in] PP_CompletionCallback callback);
250
251  /**
252   * Close() cancels any IO that may be pending, and closes the FileIO object.
253   * Any pending callbacks will still run, reporting
254   * <code>PP_ERROR_ABORTED</code> if pending IO was interrupted.  It is not
255   * valid to call Open() again after a call to this method.
256   * <strong>Note:</strong> If the FileIO object is destroyed, and it is still
257   * open, then it will be implicitly closed, so you are not required to call
258   * Close().
259   *
260   * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
261   * FileIO.
262   */
263  void Close([in] PP_Resource file_io);
264
265  /**
266   * ReadToArray() reads from an offset in the file.  A PP_ArrayOutput must be
267   * provided so that output will be stored in its allocated buffer.  This
268   * function might perform a partial read. The FileIO object must have been
269   * opened with read access.
270   *
271   * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
272   * FileIO.
273   * @param[in] offset The offset into the file.
274   * @param[in] max_read_length The maximum number of bytes to read from
275   * <code>offset</code>.
276   * @param[in] output A <code>PP_ArrayOutput</code> to hold the output data.
277   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
278   * completion of ReadToArray().
279   *
280   * @return The number of bytes read or an error code from
281   * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was
282   * reached. It is valid to call ReadToArray() multiple times with a completion
283   * callback to queue up parallel reads from the file, but pending reads
284   * cannot be interleaved with other operations.
285   */
286  [version = 1.1]
287  int32_t ReadToArray([in] PP_Resource file_io,
288                      [in] int64_t offset,
289                      [in] int32_t max_read_length,
290                      [inout] PP_ArrayOutput output,
291                      [in] PP_CompletionCallback callback);
292};
293
294