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 Jun 11 15:21:38 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(). 139 * 140 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 141 * PP_ERROR_FAILED will be returned if the file isn't opened, and 142 * PP_ERROR_INPROGRESS will be returned if there is another operation pending. 143 */ 144 int32_t (*Query)(PP_Resource file_io, 145 struct PP_FileInfo* info, 146 struct PP_CompletionCallback callback); 147 /** 148 * Touch() Updates time stamps for the file opened by this FileIO object. 149 * This function will fail if the FileIO object has not been opened. The 150 * FileIO object must be opened, and there must be no other operations 151 * pending. 152 * 153 * @param[in] file_io A <code>PP_Resource</code> corresponding to a file 154 * FileIO. 155 * @param[in] last_access_time The last time the FileIO was accessed. 156 * @param[in] last_modified_time The last time the FileIO was modified. 157 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 158 * completion of Touch(). 159 * 160 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 161 * PP_ERROR_FAILED will be returned if the file isn't opened, and 162 * PP_ERROR_INPROGRESS will be returned if there is another operation pending. 163 */ 164 int32_t (*Touch)(PP_Resource file_io, 165 PP_Time last_access_time, 166 PP_Time last_modified_time, 167 struct PP_CompletionCallback callback); 168 /** 169 * Read() reads from an offset in the file. The size of the buffer must be 170 * large enough to hold the specified number of bytes to read. This function 171 * might perform a partial read, meaning all the requested bytes 172 * might not be returned, even if the end of the file has not been reached. 173 * 174 * ReadToArray() is preferred to Read() when doing asynchronous operations. 175 * 176 * @param[in] file_io A <code>PP_Resource</code> corresponding to a file 177 * FileIO. 178 * @param[in] offset The offset into the file. 179 * @param[in] buffer The buffer to hold the specified number of bytes read. 180 * @param[in] bytes_to_read The number of bytes to read from 181 * <code>offset</code>. 182 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 183 * completion of Read(). 184 * 185 * @return The number of bytes read or an error code from 186 * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was 187 * reached. It is valid to call Read() multiple times with a completion 188 * callback to queue up parallel reads from the file, but pending reads 189 * cannot be interleaved with other operations. 190 */ 191 int32_t (*Read)(PP_Resource file_io, 192 int64_t offset, 193 char* buffer, 194 int32_t bytes_to_read, 195 struct PP_CompletionCallback callback); 196 /** 197 * Write() writes to an offset in the file. This function might perform a 198 * partial write. The FileIO object must have been opened with write access. 199 * 200 * @param[in] file_io A <code>PP_Resource</code> corresponding to a file 201 * FileIO. 202 * @param[in] offset The offset into the file. 203 * @param[in] buffer The buffer to hold the specified number of bytes read. 204 * @param[in] bytes_to_write The number of bytes to write to 205 * <code>offset</code>. 206 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 207 * completion of Write(). 208 * 209 * @return The number of bytes written or an error code from 210 * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was 211 * reached. It is valid to call Write() multiple times with a completion 212 * callback to queue up parallel writes to the file, but pending writes 213 * cannot be interleaved with other operations. 214 */ 215 int32_t (*Write)(PP_Resource file_io, 216 int64_t offset, 217 const char* buffer, 218 int32_t bytes_to_write, 219 struct PP_CompletionCallback callback); 220 /** 221 * SetLength() sets the length of the file. If the file size is extended, 222 * then the extended area of the file is zero-filled. The FileIO object must 223 * have been opened with write access and there must be no other operations 224 * pending. 225 * 226 * @param[in] file_io A <code>PP_Resource</code> corresponding to a file 227 * FileIO. 228 * @param[in] length The length of the file to be set. 229 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 230 * completion of SetLength(). 231 * 232 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 233 * PP_ERROR_FAILED will be returned if the file isn't opened, and 234 * PP_ERROR_INPROGRESS will be returned if there is another operation pending. 235 */ 236 int32_t (*SetLength)(PP_Resource file_io, 237 int64_t length, 238 struct PP_CompletionCallback callback); 239 /** 240 * Flush() flushes changes to disk. This call can be very expensive! The 241 * FileIO object must have been opened with write access and there must be no 242 * other operations pending. 243 * 244 * @param[in] file_io A <code>PP_Resource</code> corresponding to a file 245 * FileIO. 246 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 247 * completion of Flush(). 248 * 249 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 250 * PP_ERROR_FAILED will be returned if the file isn't opened, and 251 * PP_ERROR_INPROGRESS will be returned if there is another operation pending. 252 */ 253 int32_t (*Flush)(PP_Resource file_io, struct PP_CompletionCallback callback); 254 /** 255 * Close() cancels any IO that may be pending, and closes the FileIO object. 256 * Any pending callbacks will still run, reporting 257 * <code>PP_ERROR_ABORTED</code> if pending IO was interrupted. It is not 258 * valid to call Open() again after a call to this method. 259 * <strong>Note:</strong> If the FileIO object is destroyed, and it is still 260 * open, then it will be implicitly closed, so you are not required to call 261 * Close(). 262 * 263 * @param[in] file_io A <code>PP_Resource</code> corresponding to a file 264 * FileIO. 265 */ 266 void (*Close)(PP_Resource file_io); 267 /** 268 * ReadToArray() reads from an offset in the file. A PP_ArrayOutput must be 269 * provided so that output will be stored in its allocated buffer. This 270 * function might perform a partial read. 271 * 272 * @param[in] file_io A <code>PP_Resource</code> corresponding to a file 273 * FileIO. 274 * @param[in] offset The offset into the file. 275 * @param[in] max_read_length The maximum number of bytes to read from 276 * <code>offset</code>. 277 * @param[in] output A <code>PP_ArrayOutput</code> to hold the output data. 278 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 279 * completion of ReadToArray(). 280 * 281 * @return The number of bytes read or an error code from 282 * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was 283 * reached. It is valid to call ReadToArray() multiple times with a completion 284 * callback to queue up parallel reads from the file, but pending reads 285 * cannot be interleaved with other operations. 286 */ 287 int32_t (*ReadToArray)(PP_Resource file_io, 288 int64_t offset, 289 int32_t max_read_length, 290 struct PP_ArrayOutput* output, 291 struct PP_CompletionCallback callback); 292 }; 293 294 typedef struct PPB_FileIO_1_1 PPB_FileIO; 295 296 struct PPB_FileIO_1_0 { 297 PP_Resource (*Create)(PP_Instance instance); 298 PP_Bool (*IsFileIO)(PP_Resource resource); 299 int32_t (*Open)(PP_Resource file_io, 300 PP_Resource file_ref, 301 int32_t open_flags, 302 struct PP_CompletionCallback callback); 303 int32_t (*Query)(PP_Resource file_io, 304 struct PP_FileInfo* info, 305 struct PP_CompletionCallback callback); 306 int32_t (*Touch)(PP_Resource file_io, 307 PP_Time last_access_time, 308 PP_Time last_modified_time, 309 struct PP_CompletionCallback callback); 310 int32_t (*Read)(PP_Resource file_io, 311 int64_t offset, 312 char* buffer, 313 int32_t bytes_to_read, 314 struct PP_CompletionCallback callback); 315 int32_t (*Write)(PP_Resource file_io, 316 int64_t offset, 317 const char* buffer, 318 int32_t bytes_to_write, 319 struct PP_CompletionCallback callback); 320 int32_t (*SetLength)(PP_Resource file_io, 321 int64_t length, 322 struct PP_CompletionCallback callback); 323 int32_t (*Flush)(PP_Resource file_io, struct PP_CompletionCallback callback); 324 void (*Close)(PP_Resource file_io); 325 }; 326 /** 327 * @} 328 */ 329 330 #endif /* PPAPI_C_PPB_FILE_IO_H_ */ 331 332
