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