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