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