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 Fri Nov 16 10:46:53 2012. */
   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 } PP_FileOpenFlags;
  65 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_FileOpenFlags, 4);
  66 /**
  67  * @}
  68  */
  69
  70 /**
  71  * @addtogroup Interfaces
  72  * @{
  73  */
  74 /**
  75  * The <code>PPB_FileIO</code> struct is used to operate on a regular file
  76  * (PP_FileType_Regular).
  77  */
  78 struct PPB_FileIO_1_1 {
  79   /**
  80    * Create() creates a new FileIO object.
  81    *
  82    * @param[in] instance A <code>PP_Instance</code> identifying the instance
  83    * with the file.
  84    *
  85    * @return A <code>PP_Resource</code> corresponding to a FileIO if
  86    * successful or 0 if the module is invalid.
  87    */
  88   PP_Resource (*Create)(PP_Instance instance);
  89   /**
  90    * IsFileIO() determines if the provided resource is a FileIO.
  91    *
  92    * @param[in] resource A <code>PP_Resource</code> corresponding to a FileIO.
  93    *
  94    * @return <code>PP_TRUE</code> if the resource is a
  95    * <code>PPB_FileIO</code>, <code>PP_FALSE</code> if the resource is
  96    * invalid or some type other than <code>PPB_FileIO</code>.
  97    */
  98   PP_Bool (*IsFileIO)(PP_Resource resource);
  99   /**
 100    * Open() opens the specified regular file for I/O according to the given
 101    * open flags, which is a bit-mask of the <code>PP_FileOpenFlags</code>
 102    * values. Upon success, the corresponding file is classified as "in use"
 103    * by this FileIO object until such time as the FileIO object is closed
 104    * or destroyed.
 105    *
 106    * @param[in] file_io A <code>PP_Resource</code> corresponding to a
 107    * FileIO.
 108    * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
 109    * reference.
 110    * @param[in] open_flags A bit-mask of the <code>PP_FileOpenFlags</code>
 111    * values.
 112    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 113    * completion of Open().
 114    *
 115    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 116    */
 117   int32_t (*Open)(PP_Resource file_io,
 118                   PP_Resource file_ref,
 119                   int32_t open_flags,
 120                   struct PP_CompletionCallback callback);
 121   /**
 122    * Query() queries info about the file opened by this FileIO object. The
 123    * FileIO object must be opened, and there must be no other operations
 124    * pending.
 125    *
 126    * @param[in] file_io A <code>PP_Resource</code> corresponding to a
 127    * FileIO.
 128    * @param[out] info The <code>PP_FileInfo</code> structure representing all
 129    * information about the file.
 130    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 131    * completion of Query().
 132    *
 133    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 134    * PP_ERROR_FAILED will be returned if the file isn't opened, and
 135    * PP_ERROR_INPROGRESS will be returned if there is another operation pending.
 136    */
 137   int32_t (*Query)(PP_Resource file_io,
 138                    struct PP_FileInfo* info,
 139                    struct PP_CompletionCallback callback);
 140   /**
 141    * Touch() Updates time stamps for the file opened by this FileIO object.
 142    * This function will fail if the FileIO object has not been opened. The
 143    * FileIO object must be opened, and there must be no other operations
 144    * pending.
 145    *
 146    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 147    * FileIO.
 148    * @param[in] last_access_time The last time the FileIO was accessed.
 149    * @param[in] last_modified_time The last time the FileIO was modified.
 150    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 151    * completion of Touch().
 152    *
 153    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 154    * PP_ERROR_FAILED will be returned if the file isn't opened, and
 155    * PP_ERROR_INPROGRESS will be returned if there is another operation pending.
 156    */
 157   int32_t (*Touch)(PP_Resource file_io,
 158                    PP_Time last_access_time,
 159                    PP_Time last_modified_time,
 160                    struct PP_CompletionCallback callback);
 161   /**
 162    * Read() reads from an offset in the file.  The size of the buffer must be
 163    * large enough to hold the specified number of bytes to read.  This function
 164    * might perform a partial read, meaning all the requested bytes
 165    * might not be returned, even if the end of the file has not been reached.
 166    *
 167    * ReadToArray() is preferred to Read() when doing asynchronous operations.
 168    *
 169    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 170    * FileIO.
 171    * @param[in] offset The offset into the file.
 172    * @param[in] buffer The buffer to hold the specified number of bytes read.
 173    * @param[in] bytes_to_read The number of bytes to read from
 174    * <code>offset</code>.
 175    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 176    * completion of Read().
 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)(PP_Resource file_io,
 185                   int64_t offset,
 186                   char* buffer,
 187                   int32_t bytes_to_read,
 188                   struct PP_CompletionCallback callback);
 189   /**
 190    * Write() writes to an offset in the file.  This function might perform a
 191    * partial write. The FileIO object must have been opened with write access.
 192    *
 193    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 194    * FileIO.
 195    * @param[in] offset The offset into the file.
 196    * @param[in] buffer The buffer to hold the specified number of bytes read.
 197    * @param[in] bytes_to_write The number of bytes to write to
 198    * <code>offset</code>.
 199    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 200    * completion of Write().
 201    *
 202    * @return The number of bytes written or an error code from
 203    * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was
 204    * reached. It is valid to call Write() multiple times with a completion
 205    * callback to queue up parallel writes to the file, but pending writes
 206    * cannot be interleaved with other operations.
 207    */
 208   int32_t (*Write)(PP_Resource file_io,
 209                    int64_t offset,
 210                    const char* buffer,
 211                    int32_t bytes_to_write,
 212                    struct PP_CompletionCallback callback);
 213   /**
 214    * SetLength() sets the length of the file.  If the file size is extended,
 215    * then the extended area of the file is zero-filled. The FileIO object must
 216    * have been opened with write access and there must be no other operations
 217    * pending.
 218    *
 219    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 220    * FileIO.
 221    * @param[in] length The length of the file to be set.
 222    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 223    * completion of SetLength().
 224    *
 225    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 226    * PP_ERROR_FAILED will be returned if the file isn't opened, and
 227    * PP_ERROR_INPROGRESS will be returned if there is another operation pending.
 228    */
 229   int32_t (*SetLength)(PP_Resource file_io,
 230                        int64_t length,
 231                        struct PP_CompletionCallback callback);
 232   /**
 233    * Flush() flushes changes to disk.  This call can be very expensive! The
 234    * FileIO object must have been opened with write access and there must be no
 235    * other operations pending.
 236    *
 237    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 238    * FileIO.
 239    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 240    * completion of Flush().
 241    *
 242    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 243    * PP_ERROR_FAILED will be returned if the file isn't opened, and
 244    * PP_ERROR_INPROGRESS will be returned if there is another operation pending.
 245    */
 246   int32_t (*Flush)(PP_Resource file_io, struct PP_CompletionCallback callback);
 247   /**
 248    * Close() cancels any IO that may be pending, and closes the FileIO object.
 249    * Any pending callbacks will still run, reporting
 250    * <code>PP_ERROR_ABORTED</code> if pending IO was interrupted.  It is not
 251    * valid to call Open() again after a call to this method.
 252    * <strong>Note:</strong> If the FileIO object is destroyed, and it is still
 253    * open, then it will be implicitly closed, so you are not required to call
 254    * Close().
 255    *
 256    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 257    * FileIO.
 258    */
 259   void (*Close)(PP_Resource file_io);
 260   /**
 261    * ReadToArray() reads from an offset in the file.  A PP_ArrayOutput must be
 262    * provided so that output will be stored in its allocated buffer.  This
 263    * function might perform a partial read.
 264    *
 265    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 266    * FileIO.
 267    * @param[in] offset The offset into the file.
 268    * @param[in] max_read_length The maximum number of bytes to read from
 269    * <code>offset</code>.
 270    * @param[in] output A <code>PP_ArrayOutput</code> to hold the output data.
 271    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 272    * completion of ReadToArray().
 273    *
 274    * @return The number of bytes read or an error code from
 275    * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was
 276    * reached. It is valid to call ReadToArray() multiple times with a completion
 277    * callback to queue up parallel reads from the file, but pending reads
 278    * cannot be interleaved with other operations.
 279    */
 280   int32_t (*ReadToArray)(PP_Resource file_io,
 281                          int64_t offset,
 282                          int32_t max_read_length,
 283                          struct PP_ArrayOutput* output,
 284                          struct PP_CompletionCallback callback);
 285 };
 286
 287 typedef struct PPB_FileIO_1_1 PPB_FileIO;
 288
 289 struct PPB_FileIO_1_0 {
 290   PP_Resource (*Create)(PP_Instance instance);
 291   PP_Bool (*IsFileIO)(PP_Resource resource);
 292   int32_t (*Open)(PP_Resource file_io,
 293                   PP_Resource file_ref,
 294                   int32_t open_flags,
 295                   struct PP_CompletionCallback callback);
 296   int32_t (*Query)(PP_Resource file_io,
 297                    struct PP_FileInfo* info,
 298                    struct PP_CompletionCallback callback);
 299   int32_t (*Touch)(PP_Resource file_io,
 300                    PP_Time last_access_time,
 301                    PP_Time last_modified_time,
 302                    struct PP_CompletionCallback callback);
 303   int32_t (*Read)(PP_Resource file_io,
 304                   int64_t offset,
 305                   char* buffer,
 306                   int32_t bytes_to_read,
 307                   struct PP_CompletionCallback callback);
 308   int32_t (*Write)(PP_Resource file_io,
 309                    int64_t offset,
 310                    const char* buffer,
 311                    int32_t bytes_to_write,
 312                    struct PP_CompletionCallback callback);
 313   int32_t (*SetLength)(PP_Resource file_io,
 314                        int64_t length,
 315                        struct PP_CompletionCallback callback);
 316   int32_t (*Flush)(PP_Resource file_io, struct PP_CompletionCallback callback);
 317   void (*Close)(PP_Resource file_io);
 318 };
 319 /**
 320  * @}
 321  */
 322
 323 #endif  /* PPAPI_C_PPB_FILE_IO_H_ */
 324