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