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