Home | History | Annotate | Download | only in c
      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 
    291