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