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