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