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