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 Jun 11 15:21:38 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().
 139    *
 140    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 141    * PP_ERROR_FAILED will be returned if the file isn't opened, and
 142    * PP_ERROR_INPROGRESS will be returned if there is another operation pending.
 143    */
 144   int32_t (*Query)(PP_Resource file_io,
 145                    struct PP_FileInfo* info,
 146                    struct PP_CompletionCallback callback);
 147   /**
 148    * Touch() Updates time stamps for the file opened by this FileIO object.
 149    * This function will fail if the FileIO object has not been opened. The
 150    * FileIO object must be opened, and there must be no other operations
 151    * pending.
 152    *
 153    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 154    * FileIO.
 155    * @param[in] last_access_time The last time the FileIO was accessed.
 156    * @param[in] last_modified_time The last time the FileIO was modified.
 157    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 158    * completion of Touch().
 159    *
 160    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 161    * PP_ERROR_FAILED will be returned if the file isn't opened, and
 162    * PP_ERROR_INPROGRESS will be returned if there is another operation pending.
 163    */
 164   int32_t (*Touch)(PP_Resource file_io,
 165                    PP_Time last_access_time,
 166                    PP_Time last_modified_time,
 167                    struct PP_CompletionCallback callback);
 168   /**
 169    * Read() reads from an offset in the file.  The size of the buffer must be
 170    * large enough to hold the specified number of bytes to read.  This function
 171    * might perform a partial read, meaning all the requested bytes
 172    * might not be returned, even if the end of the file has not been reached.
 173    *
 174    * ReadToArray() is preferred to Read() when doing asynchronous operations.
 175    *
 176    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 177    * FileIO.
 178    * @param[in] offset The offset into the file.
 179    * @param[in] buffer The buffer to hold the specified number of bytes read.
 180    * @param[in] bytes_to_read The number of bytes to read from
 181    * <code>offset</code>.
 182    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 183    * completion of Read().
 184    *
 185    * @return The number of bytes read or an error code from
 186    * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was
 187    * reached. It is valid to call Read() multiple times with a completion
 188    * callback to queue up parallel reads from the file, but pending reads
 189    * cannot be interleaved with other operations.
 190    */
 191   int32_t (*Read)(PP_Resource file_io,
 192                   int64_t offset,
 193                   char* buffer,
 194                   int32_t bytes_to_read,
 195                   struct PP_CompletionCallback callback);
 196   /**
 197    * Write() writes to an offset in the file.  This function might perform a
 198    * partial write. The FileIO object must have been opened with write access.
 199    *
 200    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 201    * FileIO.
 202    * @param[in] offset The offset into the file.
 203    * @param[in] buffer The buffer to hold the specified number of bytes read.
 204    * @param[in] bytes_to_write The number of bytes to write to
 205    * <code>offset</code>.
 206    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 207    * completion of Write().
 208    *
 209    * @return The number of bytes written or an error code from
 210    * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was
 211    * reached. It is valid to call Write() multiple times with a completion
 212    * callback to queue up parallel writes to the file, but pending writes
 213    * cannot be interleaved with other operations.
 214    */
 215   int32_t (*Write)(PP_Resource file_io,
 216                    int64_t offset,
 217                    const char* buffer,
 218                    int32_t bytes_to_write,
 219                    struct PP_CompletionCallback callback);
 220   /**
 221    * SetLength() sets the length of the file.  If the file size is extended,
 222    * then the extended area of the file is zero-filled. The FileIO object must
 223    * have been opened with write access and there must be no other operations
 224    * pending.
 225    *
 226    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 227    * FileIO.
 228    * @param[in] length The length of the file to be set.
 229    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 230    * completion of SetLength().
 231    *
 232    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 233    * PP_ERROR_FAILED will be returned if the file isn't opened, and
 234    * PP_ERROR_INPROGRESS will be returned if there is another operation pending.
 235    */
 236   int32_t (*SetLength)(PP_Resource file_io,
 237                        int64_t length,
 238                        struct PP_CompletionCallback callback);
 239   /**
 240    * Flush() flushes changes to disk.  This call can be very expensive! The
 241    * FileIO object must have been opened with write access and there must be no
 242    * other operations pending.
 243    *
 244    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 245    * FileIO.
 246    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 247    * completion of Flush().
 248    *
 249    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 250    * PP_ERROR_FAILED will be returned if the file isn't opened, and
 251    * PP_ERROR_INPROGRESS will be returned if there is another operation pending.
 252    */
 253   int32_t (*Flush)(PP_Resource file_io, struct PP_CompletionCallback callback);
 254   /**
 255    * Close() cancels any IO that may be pending, and closes the FileIO object.
 256    * Any pending callbacks will still run, reporting
 257    * <code>PP_ERROR_ABORTED</code> if pending IO was interrupted.  It is not
 258    * valid to call Open() again after a call to this method.
 259    * <strong>Note:</strong> If the FileIO object is destroyed, and it is still
 260    * open, then it will be implicitly closed, so you are not required to call
 261    * Close().
 262    *
 263    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 264    * FileIO.
 265    */
 266   void (*Close)(PP_Resource file_io);
 267   /**
 268    * ReadToArray() reads from an offset in the file.  A PP_ArrayOutput must be
 269    * provided so that output will be stored in its allocated buffer.  This
 270    * function might perform a partial read.
 271    *
 272    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 273    * FileIO.
 274    * @param[in] offset The offset into the file.
 275    * @param[in] max_read_length The maximum number of bytes to read from
 276    * <code>offset</code>.
 277    * @param[in] output A <code>PP_ArrayOutput</code> to hold the output data.
 278    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 279    * completion of ReadToArray().
 280    *
 281    * @return The number of bytes read or an error code from
 282    * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was
 283    * reached. It is valid to call ReadToArray() multiple times with a completion
 284    * callback to queue up parallel reads from the file, but pending reads
 285    * cannot be interleaved with other operations.
 286    */
 287   int32_t (*ReadToArray)(PP_Resource file_io,
 288                          int64_t offset,
 289                          int32_t max_read_length,
 290                          struct PP_ArrayOutput* output,
 291                          struct PP_CompletionCallback callback);
 292 };
 293
 294 typedef struct PPB_FileIO_1_1 PPB_FileIO;
 295
 296 struct PPB_FileIO_1_0 {
 297   PP_Resource (*Create)(PP_Instance instance);
 298   PP_Bool (*IsFileIO)(PP_Resource resource);
 299   int32_t (*Open)(PP_Resource file_io,
 300                   PP_Resource file_ref,
 301                   int32_t open_flags,
 302                   struct PP_CompletionCallback callback);
 303   int32_t (*Query)(PP_Resource file_io,
 304                    struct PP_FileInfo* info,
 305                    struct PP_CompletionCallback callback);
 306   int32_t (*Touch)(PP_Resource file_io,
 307                    PP_Time last_access_time,
 308                    PP_Time last_modified_time,
 309                    struct PP_CompletionCallback callback);
 310   int32_t (*Read)(PP_Resource file_io,
 311                   int64_t offset,
 312                   char* buffer,
 313                   int32_t bytes_to_read,
 314                   struct PP_CompletionCallback callback);
 315   int32_t (*Write)(PP_Resource file_io,
 316                    int64_t offset,
 317                    const char* buffer,
 318                    int32_t bytes_to_write,
 319                    struct PP_CompletionCallback callback);
 320   int32_t (*SetLength)(PP_Resource file_io,
 321                        int64_t length,
 322                        struct PP_CompletionCallback callback);
 323   int32_t (*Flush)(PP_Resource file_io, struct PP_CompletionCallback callback);
 324   void (*Close)(PP_Resource file_io);
 325 };
 326 /**
 327  * @}
 328  */
 329
 330 #endif  /* PPAPI_C_PPB_FILE_IO_H_ */
 331