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