ppapi/c/ppb_file_ref.h

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