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 /** 8 * This file defines the API to create a file i/o object. 9 */ 10 11 [generate_thunk] 12 13 label Chrome { 14 M14 = 1.0, 15 M25 = 1.1, 16 M29 = 1.2 17 }; 18 19 /** 20 * The PP_FileOpenFlags enum contains file open constants. 21 */ 22 [assert_size(4)] 23 enum PP_FileOpenFlags { 24 /** Requests read access to a file. */ 25 PP_FILEOPENFLAG_READ = 1 << 0, 26 27 /** 28 * Requests write access to a file. May be combined with 29 * <code>PP_FILEOPENFLAG_READ</code> to request read and write access. 30 */ 31 PP_FILEOPENFLAG_WRITE = 1 << 1, 32 33 /** 34 * Requests that the file be created if it does not exist. If the file 35 * already exists, then this flag is ignored unless 36 * <code>PP_FILEOPENFLAG_EXCLUSIVE</code> was also specified, in which case 37 * FileIO::Open() will fail. 38 */ 39 PP_FILEOPENFLAG_CREATE = 1 << 2, 40 41 /** 42 * Requests that the file be truncated to length 0 if it exists and is a 43 * regular file. <code>PP_FILEOPENFLAG_WRITE</code> must also be specified. 44 */ 45 PP_FILEOPENFLAG_TRUNCATE = 1 << 3, 46 47 /** 48 * Requests that the file is created when this flag is combined with 49 * <code>PP_FILEOPENFLAG_CREATE</code>. If this flag is specified, and the 50 * file already exists, then the FileIO::Open() call will fail. 51 */ 52 PP_FILEOPENFLAG_EXCLUSIVE = 1 << 4, 53 54 /** 55 * Requests write access to a file, but writes will always occur at the end of 56 * the file. Mututally exclusive with <code>PP_FILEOPENFLAG_WRITE</code>. 57 * 58 * This is only supported in version 1.2 (Chrome 29) and later. 59 */ 60 [version=1.2] 61 PP_FILEOPENFLAG_APPEND = 1 << 5 62 }; 63 64 65 /** 66 * The <code>PPB_FileIO</code> struct is used to operate on a regular file 67 * (PP_FileType_Regular). 68 */ 69 interface PPB_FileIO { 70 /** 71 * Create() creates a new FileIO object. 72 * 73 * @param[in] instance A <code>PP_Instance</code> identifying the instance 74 * with the file. 75 * 76 * @return A <code>PP_Resource</code> corresponding to a FileIO if 77 * successful or 0 if the module is invalid. 78 */ 79 PP_Resource Create([in] PP_Instance instance); 80 /** 81 * IsFileIO() determines if the provided resource is a FileIO. 82 * 83 * @param[in] resource A <code>PP_Resource</code> corresponding to a FileIO. 84 * 85 * @return <code>PP_TRUE</code> if the resource is a 86 * <code>PPB_FileIO</code>, <code>PP_FALSE</code> if the resource is 87 * invalid or some type other than <code>PPB_FileIO</code>. 88 */ 89 PP_Bool IsFileIO([in] PP_Resource resource); 90 91 /** 92 * Open() opens the specified regular file for I/O according to the given 93 * open flags, which is a bit-mask of the <code>PP_FileOpenFlags</code> 94 * values. Upon success, the corresponding file is classified as "in use" 95 * by this FileIO object until such time as the FileIO object is closed 96 * or destroyed. 97 * 98 * @param[in] file_io A <code>PP_Resource</code> corresponding to a 99 * FileIO. 100 * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file 101 * reference. 102 * @param[in] open_flags A bit-mask of the <code>PP_FileOpenFlags</code> 103 * values. 104 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 105 * completion of Open(). 106 * 107 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 108 */ 109 int32_t Open([in] PP_Resource file_io, 110 [in] PP_Resource file_ref, 111 [in] int32_t open_flags, 112 [in] PP_CompletionCallback callback); 113 114 /** 115 * Query() queries info about the file opened by this FileIO object. The 116 * FileIO object must be opened, and there must be no other operations 117 * pending. 118 * 119 * @param[in] file_io A <code>PP_Resource</code> corresponding to a 120 * FileIO. 121 * @param[out] info The <code>PP_FileInfo</code> structure representing all 122 * information about the file. 123 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 124 * completion of Query(). <code>info</code> must remain valid until after the 125 * callback runs. If you pass a blocking callback, <code>info</code> must 126 * remain valid until after Query() returns. 127 * 128 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 129 * PP_ERROR_FAILED will be returned if the file isn't opened, and 130 * PP_ERROR_INPROGRESS will be returned if there is another operation pending. 131 */ 132 int32_t Query([in] PP_Resource file_io, 133 [out] PP_FileInfo info, 134 [in] PP_CompletionCallback callback); 135 136 /** 137 * Touch() Updates time stamps for the file opened by this FileIO object. 138 * This function will fail if the FileIO object has not been opened. The 139 * FileIO object must be opened, and there must be no other operations 140 * pending. 141 * 142 * @param[in] file_io A <code>PP_Resource</code> corresponding to a file 143 * FileIO. 144 * @param[in] last_access_time The last time the FileIO was accessed. 145 * @param[in] last_modified_time The last time the FileIO was modified. 146 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 147 * completion of Touch(). 148 * 149 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 150 * PP_ERROR_FAILED will be returned if the file isn't opened, and 151 * PP_ERROR_INPROGRESS will be returned if there is another operation pending. 152 */ 153 int32_t Touch([in] PP_Resource file_io, 154 [in] PP_Time last_access_time, 155 [in] PP_Time last_modified_time, 156 [in] PP_CompletionCallback callback); 157 158 /** 159 * Read() reads from an offset in the file. The size of the buffer must be 160 * large enough to hold the specified number of bytes to read. This function 161 * might perform a partial read, meaning all the requested bytes 162 * might not be returned, even if the end of the file has not been reached. 163 * The FileIO object must have been opened with read access. 164 * 165 * ReadToArray() is preferred to Read() when doing asynchronous operations. 166 * 167 * @param[in] file_io A <code>PP_Resource</code> corresponding to a file 168 * FileIO. 169 * @param[in] offset The offset into the file. 170 * @param[in] buffer The buffer to hold the specified number of bytes read. 171 * @param[in] bytes_to_read The number of bytes to read from 172 * <code>offset</code>. 173 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 174 * completion of Read(). <code>buffer</code> must remain valid until after 175 * the callback runs. If you pass a blocking callback, <code>buffer</code> 176 * must remain valid until after Read() returns. 177 * 178 * @return The number of bytes read or an error code from 179 * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was 180 * reached. It is valid to call Read() multiple times with a completion 181 * callback to queue up parallel reads from the file, but pending reads 182 * cannot be interleaved with other operations. 183 */ 184 int32_t Read([in] PP_Resource file_io, 185 [in] int64_t offset, 186 [inout] str_t buffer, 187 [in] int32_t bytes_to_read, 188 [in] PP_CompletionCallback callback); 189 190 /** 191 * Write() writes to an offset in the file. This function might perform a 192 * partial write. The FileIO object must have been opened with write access. 193 * 194 * @param[in] file_io A <code>PP_Resource</code> corresponding to a file 195 * FileIO. 196 * @param[in] offset The offset into the file. 197 * @param[in] buffer The buffer to hold the specified number of bytes read. 198 * @param[in] bytes_to_write The number of bytes to write to 199 * <code>offset</code>. 200 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 201 * completion of Write(). 202 * 203 * @return The number of bytes written or an error code from 204 * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was 205 * reached. It is valid to call Write() multiple times with a completion 206 * callback to queue up parallel writes to the file, but pending writes 207 * cannot be interleaved with other operations. 208 */ 209 int32_t Write([in] PP_Resource file_io, 210 [in] int64_t offset, 211 [in] str_t buffer, 212 [in] int32_t bytes_to_write, 213 [in] PP_CompletionCallback callback); 214 /** 215 * SetLength() sets the length of the file. If the file size is extended, 216 * then the extended area of the file is zero-filled. The FileIO object must 217 * have been opened with write access and there must be no other operations 218 * pending. 219 * 220 * @param[in] file_io A <code>PP_Resource</code> corresponding to a file 221 * FileIO. 222 * @param[in] length The length of the file to be set. 223 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 224 * completion of SetLength(). 225 * 226 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 227 * PP_ERROR_FAILED will be returned if the file isn't opened, and 228 * PP_ERROR_INPROGRESS will be returned if there is another operation pending. 229 */ 230 int32_t SetLength([in] PP_Resource file_io, 231 [in] int64_t length, 232 [in] PP_CompletionCallback callback); 233 234 /** 235 * Flush() flushes changes to disk. This call can be very expensive! The 236 * FileIO object must have been opened with write access and there must be no 237 * other operations pending. 238 * 239 * @param[in] file_io A <code>PP_Resource</code> corresponding to a file 240 * FileIO. 241 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 242 * completion of Flush(). 243 * 244 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 245 * PP_ERROR_FAILED will be returned if the file isn't opened, and 246 * PP_ERROR_INPROGRESS will be returned if there is another operation pending. 247 */ 248 int32_t Flush([in] PP_Resource file_io, 249 [in] PP_CompletionCallback callback); 250 251 /** 252 * Close() cancels any IO that may be pending, and closes the FileIO object. 253 * Any pending callbacks will still run, reporting 254 * <code>PP_ERROR_ABORTED</code> if pending IO was interrupted. It is not 255 * valid to call Open() again after a call to this method. 256 * <strong>Note:</strong> If the FileIO object is destroyed, and it is still 257 * open, then it will be implicitly closed, so you are not required to call 258 * Close(). 259 * 260 * @param[in] file_io A <code>PP_Resource</code> corresponding to a file 261 * FileIO. 262 */ 263 void Close([in] PP_Resource file_io); 264 265 /** 266 * ReadToArray() reads from an offset in the file. A PP_ArrayOutput must be 267 * provided so that output will be stored in its allocated buffer. This 268 * function might perform a partial read. The FileIO object must have been 269 * opened with read access. 270 * 271 * @param[in] file_io A <code>PP_Resource</code> corresponding to a file 272 * FileIO. 273 * @param[in] offset The offset into the file. 274 * @param[in] max_read_length The maximum number of bytes to read from 275 * <code>offset</code>. 276 * @param[in] output A <code>PP_ArrayOutput</code> to hold the output data. 277 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 278 * completion of ReadToArray(). 279 * 280 * @return The number of bytes read or an error code from 281 * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was 282 * reached. It is valid to call ReadToArray() multiple times with a completion 283 * callback to queue up parallel reads from the file, but pending reads 284 * cannot be interleaved with other operations. 285 */ 286 [version = 1.1] 287 int32_t ReadToArray([in] PP_Resource file_io, 288 [in] int64_t offset, 289 [in] int32_t max_read_length, 290 [inout] PP_ArrayOutput output, 291 [in] PP_CompletionCallback callback); 292 }; 293 294
