ppapi/c/ppb_file_io.h

   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  */
  38 typedef 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;
  72 PP_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  */
  85 struct 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
 300 typedef struct PPB_FileIO_1_1 PPB_FileIO;
 301
 302 struct 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