ppapi/api/ppb_file_io.idl

   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
  13 label 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  */
  69 interface 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().
 125    *
 126    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 127    * PP_ERROR_FAILED will be returned if the file isn't opened, and
 128    * PP_ERROR_INPROGRESS will be returned if there is another operation pending.
 129    */
 130   int32_t Query([in] PP_Resource file_io,
 131                 [out] PP_FileInfo info,
 132                 [in] PP_CompletionCallback callback);
 133
 134   /**
 135    * Touch() Updates time stamps for the file opened by this FileIO object.
 136    * This function will fail if the FileIO object has not been opened. The
 137    * FileIO object must be opened, and there must be no other operations
 138    * pending.
 139    *
 140    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 141    * FileIO.
 142    * @param[in] last_access_time The last time the FileIO was accessed.
 143    * @param[in] last_modified_time The last time the FileIO was modified.
 144    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 145    * completion of Touch().
 146    *
 147    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 148    * PP_ERROR_FAILED will be returned if the file isn't opened, and
 149    * PP_ERROR_INPROGRESS will be returned if there is another operation pending.
 150    */
 151   int32_t Touch([in] PP_Resource file_io,
 152                 [in] PP_Time last_access_time,
 153                 [in] PP_Time last_modified_time,
 154                 [in] PP_CompletionCallback callback);
 155
 156   /**
 157    * Read() reads from an offset in the file.  The size of the buffer must be
 158    * large enough to hold the specified number of bytes to read.  This function
 159    * might perform a partial read, meaning all the requested bytes
 160    * might not be returned, even if the end of the file has not been reached.
 161    *
 162    * ReadToArray() is preferred to Read() when doing asynchronous operations.
 163    *
 164    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 165    * FileIO.
 166    * @param[in] offset The offset into the file.
 167    * @param[in] buffer The buffer to hold the specified number of bytes read.
 168    * @param[in] bytes_to_read The number of bytes to read from
 169    * <code>offset</code>.
 170    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 171    * completion of Read().
 172    *
 173    * @return The number of bytes read or an error code from
 174    * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was
 175    * reached. It is valid to call Read() multiple times with a completion
 176    * callback to queue up parallel reads from the file, but pending reads
 177    * cannot be interleaved with other operations.
 178    */
 179   int32_t Read([in] PP_Resource file_io,
 180                [in] int64_t offset,
 181                [inout] str_t buffer,
 182                [in] int32_t bytes_to_read,
 183                [in] PP_CompletionCallback callback);
 184
 185   /**
 186    * Write() writes to an offset in the file.  This function might perform a
 187    * partial write. The FileIO object must have been opened with write access.
 188    *
 189    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 190    * FileIO.
 191    * @param[in] offset The offset into the file.
 192    * @param[in] buffer The buffer to hold the specified number of bytes read.
 193    * @param[in] bytes_to_write The number of bytes to write to
 194    * <code>offset</code>.
 195    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 196    * completion of Write().
 197    *
 198    * @return The number of bytes written or an error code from
 199    * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was
 200    * reached. It is valid to call Write() multiple times with a completion
 201    * callback to queue up parallel writes to the file, but pending writes
 202    * cannot be interleaved with other operations.
 203    */
 204   int32_t Write([in] PP_Resource file_io,
 205                 [in] int64_t offset,
 206                 [in] str_t buffer,
 207                 [in] int32_t bytes_to_write,
 208                 [in] PP_CompletionCallback callback);
 209   /**
 210    * SetLength() sets the length of the file.  If the file size is extended,
 211    * then the extended area of the file is zero-filled. The FileIO object must
 212    * have been opened with write access and there must be no other operations
 213    * pending.
 214    *
 215    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 216    * FileIO.
 217    * @param[in] length The length of the file to be set.
 218    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 219    * completion of SetLength().
 220    *
 221    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 222    * PP_ERROR_FAILED will be returned if the file isn't opened, and
 223    * PP_ERROR_INPROGRESS will be returned if there is another operation pending.
 224    */
 225   int32_t SetLength([in] PP_Resource file_io,
 226                     [in] int64_t length,
 227                     [in] PP_CompletionCallback callback);
 228
 229   /**
 230    * Flush() flushes changes to disk.  This call can be very expensive! The
 231    * FileIO object must have been opened with write access and there must be no
 232    * other operations pending.
 233    *
 234    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 235    * FileIO.
 236    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 237    * completion of Flush().
 238    *
 239    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 240    * PP_ERROR_FAILED will be returned if the file isn't opened, and
 241    * PP_ERROR_INPROGRESS will be returned if there is another operation pending.
 242    */
 243   int32_t Flush([in] PP_Resource file_io,
 244                 [in] PP_CompletionCallback callback);
 245
 246   /**
 247    * Close() cancels any IO that may be pending, and closes the FileIO object.
 248    * Any pending callbacks will still run, reporting
 249    * <code>PP_ERROR_ABORTED</code> if pending IO was interrupted.  It is not
 250    * valid to call Open() again after a call to this method.
 251    * <strong>Note:</strong> If the FileIO object is destroyed, and it is still
 252    * open, then it will be implicitly closed, so you are not required to call
 253    * Close().
 254    *
 255    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
 256    * FileIO.
 257    */
 258   void Close([in] PP_Resource file_io);
 259
 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   [version = 1.1]
 281   int32_t ReadToArray([in] PP_Resource file_io,
 282                       [in] int64_t offset,
 283                       [in] int32_t max_read_length,
 284                       [inout] PP_ArrayOutput output,
 285                       [in] PP_CompletionCallback callback);
 286 };
 287