ppapi/api/ppb_file_ref.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  * This file defines the API to create a file reference or "weak pointer" to a
   8  * file in a file system.
   9  */
  10
  11 label Chrome {
  12   M14 = 1.0,
  13   M28 = 1.1,
  14   M34 = 1.2
  15 };
  16
  17 /**
  18  * The <code>PP_MakeDirectoryFlags</code> enum contains flags used to control
  19  * behavior of <code>PPB_FileRef.MakeDirectory()</code>.
  20  */
  21 enum PP_MakeDirectoryFlags {
  22   PP_MAKEDIRECTORYFLAG_NONE           = 0 << 0,
  23
  24   /** Requests that ancestor directories are created if they do not exist. */
  25   PP_MAKEDIRECTORYFLAG_WITH_ANCESTORS = 1 << 0,
  26
  27   /**
  28    * Requests that the PPB_FileRef.MakeDirectory() call fails if the directory
  29    * already exists.
  30    */
  31   PP_MAKEDIRECTORYFLAG_EXCLUSIVE      = 1 << 1
  32 };
  33
  34 /**
  35  * The <code>PPB_FileRef</code> struct represents a "weak pointer" to a file in
  36  * a file system.  This struct contains a <code>PP_FileSystemType</code>
  37  * identifier and a file path string.
  38  */
  39 interface PPB_FileRef {
  40   /**
  41    * Create() creates a weak pointer to a file in the given file system. File
  42    * paths are POSIX style.
  43    *
  44    * @param[in] resource A <code>PP_Resource</code> corresponding to a file
  45    * system.
  46    * @param[in] path A path to the file. Must begin with a '/' character.
  47    *
  48    * @return A <code>PP_Resource</code> corresponding to a file reference if
  49    * successful or 0 if the path is malformed.
  50    */
  51   PP_Resource Create([in] PP_Resource file_system, [in] str_t path);
  52   /**
  53    * IsFileRef() determines if the provided resource is a file reference.
  54    *
  55    * @param[in] resource A <code>PP_Resource</code> corresponding to a file
  56    * reference.
  57    *
  58    * @return <code>PP_TRUE</code> if the resource is a
  59    * <code>PPB_FileRef</code>, <code>PP_FALSE</code> if the resource is
  60    * invalid or some type other than <code>PPB_FileRef</code>.
  61    */
  62   PP_Bool IsFileRef([in] PP_Resource resource);
  63
  64   /**
  65    * GetFileSystemType() returns the type of the file system.
  66    *
  67    * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
  68    * reference.
  69    *
  70    * @return A <code>PP_FileSystemType</code> with the file system type if
  71    * valid or <code>PP_FILESYSTEMTYPE_INVALID</code> if the provided resource
  72    * is not a valid file reference.
  73    */
  74   PP_FileSystemType GetFileSystemType([in] PP_Resource file_ref);
  75
  76   /**
  77    * GetName() returns the name of the file.
  78    *
  79    * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
  80    * reference.
  81    *
  82    * @return A <code>PP_Var</code> containing the name of the file.  The value
  83    * returned by this function does not include any path components (such as
  84    * the name of the parent directory, for example). It is just the name of the
  85    * file. Use GetPath() to get the full file path.
  86    */
  87   PP_Var GetName([in] PP_Resource file_ref);
  88
  89   /**
  90    * GetPath() returns the absolute path of the file.
  91    *
  92    * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
  93    * reference.
  94    *
  95    * @return A <code>PP_Var</code> containing the absolute path of the file.
  96    * This function fails if the file system type is
  97    * <code>PP_FileSystemType_External</code>.
  98    */
  99   PP_Var GetPath([in] PP_Resource file_ref);
 100
 101   /**
 102    * GetParent() returns the parent directory of this file.  If
 103    * <code>file_ref</code> points to the root of the filesystem, then the root
 104    * is returned.
 105    *
 106    * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
 107    * reference.
 108    *
 109    * @return A <code>PP_Resource</code> containing the parent directory of the
 110    * file. This function fails if the file system type is
 111    * <code>PP_FileSystemType_External</code>.
 112    */
 113   PP_Resource GetParent([in] PP_Resource file_ref);
 114
 115   /**
 116    * MakeDirectory() makes a new directory in the file system as well as any
 117    * parent directories if the <code>make_ancestors</code> argument is
 118    * <code>PP_TRUE</code>.  It is not valid to make a directory in the external
 119    * file system.
 120    *
 121    * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
 122    * reference.
 123    * @param[in] make_ancestors A <code>PP_Bool</code> set to
 124    * <code>PP_TRUE</code> to make ancestor directories or <code>PP_FALSE</code>
 125    * if ancestor directories are not needed.
 126    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 127    * completion of MakeDirectory().
 128    *
 129    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 130    * Succeeds if the directory already exists. Fails if ancestor directories
 131    * do not exist and <code>make_ancestors</code> was passed as
 132    * <code>PP_FALSE</code>.
 133    */
 134   [deprecate=1.2]
 135   int32_t MakeDirectory([in] PP_Resource directory_ref,
 136                         [in] PP_Bool make_ancestors,
 137                         [in] PP_CompletionCallback callback);
 138
 139   /**
 140    * MakeDirectory() makes a new directory in the file system according to the
 141    * given <code>make_directory_flags</code>, which is a bit-mask of the
 142    * <code>PP_MakeDirectoryFlags</code> values.  It is not valid to make a
 143    * directory in the external file system.
 144    *
 145    * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
 146    * reference.
 147    * @param[in] make_directory_flags A bit-mask of the
 148    * <code>PP_MakeDirectoryFlags</code> values.
 149    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 150    * completion of MakeDirectory().
 151    *
 152    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 153    */
 154   [version=1.2]
 155   int32_t MakeDirectory([in] PP_Resource directory_ref,
 156                         [in] int32_t make_directory_flags,
 157                         [in] PP_CompletionCallback callback);
 158
 159   /**
 160    * Touch() Updates time stamps for a file.  You must have write access to the
 161    * file if it exists in the external filesystem.
 162    *
 163    * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
 164    * reference.
 165    * @param[in] last_access_time The last time the file was accessed.
 166    * @param[in] last_modified_time The last time the file was modified.
 167    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 168    * completion of Touch().
 169    *
 170    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 171    */
 172   int32_t Touch([in] PP_Resource file_ref,
 173                 [in] PP_Time last_access_time,
 174                 [in] PP_Time last_modified_time,
 175                 [in] PP_CompletionCallback callback);
 176
 177   /**
 178    * Delete() deletes a file or directory. If <code>file_ref</code> refers to
 179    * a directory, then the directory must be empty. It is an error to delete a
 180    * file or directory that is in use.  It is not valid to delete a file in
 181    * the external file system.
 182    *
 183    * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
 184    * reference.
 185    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 186    * completion of Delete().
 187    *
 188    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 189    */
 190   int32_t Delete([in] PP_Resource file_ref,
 191                  [in] PP_CompletionCallback callback);
 192
 193   /**
 194    * Rename() renames a file or directory.  Arguments <code>file_ref</code> and
 195    * <code>new_file_ref</code> must both refer to files in the same file
 196    * system. It is an error to rename a file or directory that is in use.  It
 197    * is not valid to rename a file in the external file system.
 198    *
 199    * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
 200    * reference.
 201    * @param[in] new_file_ref A <code>PP_Resource</code> corresponding to a new
 202    * file reference.
 203    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 204    * completion of Rename().
 205    *
 206    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 207    */
 208   int32_t Rename([in] PP_Resource file_ref,
 209                  [in] PP_Resource new_file_ref,
 210                  [in] PP_CompletionCallback callback);
 211
 212   /**
 213    * Query() queries info about a file or directory. You must have access to
 214    * read this file or directory if it exists in the external filesystem.
 215    *
 216    * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
 217    * reference.
 218    * @param[out] info A pointer to a <code>PP_FileInfo</code> which will be
 219    * populated with information about the file or directory.
 220    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 221    * completion of Query().
 222    *
 223    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 224    */
 225   [version=1.1]
 226   int32_t Query([in] PP_Resource file_ref,
 227                 [out] PP_FileInfo info,
 228                 [in] PP_CompletionCallback callback);
 229
 230   /**
 231    * ReadDirectoryEntries() reads all entries in a directory.
 232    *
 233    * @param[in] file_ref A <code>PP_Resource</code> corresponding to a directory
 234    * reference.
 235    * @param[in] output An output array which will receive
 236    * <code>PP_DirectoryEntry</code> objects on success.
 237    * @param[in] callback A <code>PP_CompletionCallback</code> to run on
 238    * completion.
 239    *
 240    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 241    */
 242   [version=1.1]
 243   int32_t ReadDirectoryEntries([in] PP_Resource file_ref,
 244                                [in] PP_ArrayOutput output,
 245                                [in] PP_CompletionCallback callback);
 246 };
 247