/* Copyright (c) 2012 The Chromium Authors. All rights reserved.
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*/
/**
* This file defines the API to create a file i/o object.
*/
[generate_thunk]
label Chrome {
M14 = 1.0,
M25 = 1.1
};
/**
* The PP_FileOpenFlags enum contains file open constants.
*/
[assert_size(4)]
enum PP_FileOpenFlags {
/** Requests read access to a file. */
PP_FILEOPENFLAG_READ = 1 << 0,
/**
* Requests write access to a file. May be combined with
* PP_FILEOPENFLAG_READ
to request read and write access.
*/
PP_FILEOPENFLAG_WRITE = 1 << 1,
/**
* Requests that the file be created if it does not exist. If the file
* already exists, then this flag is ignored unless
* PP_FILEOPENFLAG_EXCLUSIVE
was also specified, in which case
* FileIO::Open() will fail.
*/
PP_FILEOPENFLAG_CREATE = 1 << 2,
/**
* Requests that the file be truncated to length 0 if it exists and is a
* regular file. PP_FILEOPENFLAG_WRITE
must also be specified.
*/
PP_FILEOPENFLAG_TRUNCATE = 1 << 3,
/**
* Requests that the file is created when this flag is combined with
* PP_FILEOPENFLAG_CREATE
. If this flag is specified, and the
* file already exists, then the FileIO::Open() call will fail.
*/
PP_FILEOPENFLAG_EXCLUSIVE = 1 << 4
};
/**
* The PPB_FileIO
struct is used to operate on a regular file
* (PP_FileType_Regular).
*/
interface PPB_FileIO {
/**
* Create() creates a new FileIO object.
*
* @param[in] instance A PP_Instance
identifying the instance
* with the file.
*
* @return A PP_Resource
corresponding to a FileIO if
* successful or 0 if the module is invalid.
*/
PP_Resource Create([in] PP_Instance instance);
/**
* IsFileIO() determines if the provided resource is a FileIO.
*
* @param[in] resource A PP_Resource
corresponding to a FileIO.
*
* @return PP_TRUE
if the resource is a
* PPB_FileIO
, PP_FALSE
if the resource is
* invalid or some type other than PPB_FileIO
.
*/
PP_Bool IsFileIO([in] PP_Resource resource);
/**
* Open() opens the specified regular file for I/O according to the given
* open flags, which is a bit-mask of the PP_FileOpenFlags
* values. Upon success, the corresponding file is classified as "in use"
* by this FileIO object until such time as the FileIO object is closed
* or destroyed.
*
* @param[in] file_io A PP_Resource
corresponding to a
* FileIO.
* @param[in] file_ref A PP_Resource
corresponding to a file
* reference.
* @param[in] open_flags A bit-mask of the PP_FileOpenFlags
* values.
* @param[in] callback A PP_CompletionCallback
to be called upon
* completion of Open().
*
* @return An int32_t containing an error code from pp_errors.h
.
*/
int32_t Open([in] PP_Resource file_io,
[in] PP_Resource file_ref,
[in] int32_t open_flags,
[in] PP_CompletionCallback callback);
/**
* Query() queries info about the file opened by this FileIO object. The
* FileIO object must be opened, and there must be no other operations
* pending.
*
* @param[in] file_io A PP_Resource
corresponding to a
* FileIO.
* @param[out] info The PP_FileInfo
structure representing all
* information about the file.
* @param[in] callback A PP_CompletionCallback
to be called upon
* completion of Query().
*
* @return An int32_t containing an error code from pp_errors.h
.
* PP_ERROR_FAILED will be returned if the file isn't opened, and
* PP_ERROR_INPROGRESS will be returned if there is another operation pending.
*/
int32_t Query([in] PP_Resource file_io,
[out] PP_FileInfo info,
[in] PP_CompletionCallback callback);
/**
* Touch() Updates time stamps for the file opened by this FileIO object.
* This function will fail if the FileIO object has not been opened. The
* FileIO object must be opened, and there must be no other operations
* pending.
*
* @param[in] file_io A PP_Resource
corresponding to a file
* FileIO.
* @param[in] last_access_time The last time the FileIO was accessed.
* @param[in] last_modified_time The last time the FileIO was modified.
* @param[in] callback A PP_CompletionCallback
to be called upon
* completion of Touch().
*
* @return An int32_t containing an error code from pp_errors.h
.
* PP_ERROR_FAILED will be returned if the file isn't opened, and
* PP_ERROR_INPROGRESS will be returned if there is another operation pending.
*/
int32_t Touch([in] PP_Resource file_io,
[in] PP_Time last_access_time,
[in] PP_Time last_modified_time,
[in] PP_CompletionCallback callback);
/**
* Read() reads from an offset in the file. The size of the buffer must be
* large enough to hold the specified number of bytes to read. This function
* might perform a partial read, meaning all the requested bytes
* might not be returned, even if the end of the file has not been reached.
*
* ReadToArray() is preferred to Read() when doing asynchronous operations.
*
* @param[in] file_io A PP_Resource
corresponding to a file
* FileIO.
* @param[in] offset The offset into the file.
* @param[in] buffer The buffer to hold the specified number of bytes read.
* @param[in] bytes_to_read The number of bytes to read from
* offset
.
* @param[in] callback A PP_CompletionCallback
to be called upon
* completion of Read().
*
* @return The number of bytes read or an error code from
* pp_errors.h
. If the return value is 0, then end-of-file was
* reached. It is valid to call Read() multiple times with a completion
* callback to queue up parallel reads from the file, but pending reads
* cannot be interleaved with other operations.
*/
int32_t Read([in] PP_Resource file_io,
[in] int64_t offset,
[inout] str_t buffer,
[in] int32_t bytes_to_read,
[in] PP_CompletionCallback callback);
/**
* Write() writes to an offset in the file. This function might perform a
* partial write. The FileIO object must have been opened with write access.
*
* @param[in] file_io A PP_Resource
corresponding to a file
* FileIO.
* @param[in] offset The offset into the file.
* @param[in] buffer The buffer to hold the specified number of bytes read.
* @param[in] bytes_to_write The number of bytes to write to
* offset
.
* @param[in] callback A PP_CompletionCallback
to be called upon
* completion of Write().
*
* @return The number of bytes written or an error code from
* pp_errors.h
. If the return value is 0, then end-of-file was
* reached. It is valid to call Write() multiple times with a completion
* callback to queue up parallel writes to the file, but pending writes
* cannot be interleaved with other operations.
*/
int32_t Write([in] PP_Resource file_io,
[in] int64_t offset,
[in] str_t buffer,
[in] int32_t bytes_to_write,
[in] PP_CompletionCallback callback);
/**
* SetLength() sets the length of the file. If the file size is extended,
* then the extended area of the file is zero-filled. The FileIO object must
* have been opened with write access and there must be no other operations
* pending.
*
* @param[in] file_io A PP_Resource
corresponding to a file
* FileIO.
* @param[in] length The length of the file to be set.
* @param[in] callback A PP_CompletionCallback
to be called upon
* completion of SetLength().
*
* @return An int32_t containing an error code from pp_errors.h
.
* PP_ERROR_FAILED will be returned if the file isn't opened, and
* PP_ERROR_INPROGRESS will be returned if there is another operation pending.
*/
int32_t SetLength([in] PP_Resource file_io,
[in] int64_t length,
[in] PP_CompletionCallback callback);
/**
* Flush() flushes changes to disk. This call can be very expensive! The
* FileIO object must have been opened with write access and there must be no
* other operations pending.
*
* @param[in] file_io A PP_Resource
corresponding to a file
* FileIO.
* @param[in] callback A PP_CompletionCallback
to be called upon
* completion of Flush().
*
* @return An int32_t containing an error code from pp_errors.h
.
* PP_ERROR_FAILED will be returned if the file isn't opened, and
* PP_ERROR_INPROGRESS will be returned if there is another operation pending.
*/
int32_t Flush([in] PP_Resource file_io,
[in] PP_CompletionCallback callback);
/**
* Close() cancels any IO that may be pending, and closes the FileIO object.
* Any pending callbacks will still run, reporting
* PP_ERROR_ABORTED
if pending IO was interrupted. It is not
* valid to call Open() again after a call to this method.
* Note: If the FileIO object is destroyed, and it is still
* open, then it will be implicitly closed, so you are not required to call
* Close().
*
* @param[in] file_io A PP_Resource
corresponding to a file
* FileIO.
*/
void Close([in] PP_Resource file_io);
/**
* ReadToArray() reads from an offset in the file. A PP_ArrayOutput must be
* provided so that output will be stored in its allocated buffer. This
* function might perform a partial read.
*
* @param[in] file_io A PP_Resource
corresponding to a file
* FileIO.
* @param[in] offset The offset into the file.
* @param[in] max_read_length The maximum number of bytes to read from
* offset
.
* @param[in] output A PP_ArrayOutput
to hold the output data.
* @param[in] callback A PP_CompletionCallback
to be called upon
* completion of ReadToArray().
*
* @return The number of bytes read or an error code from
* pp_errors.h
. If the return value is 0, then end-of-file was
* reached. It is valid to call ReadToArray() multiple times with a completion
* callback to queue up parallel reads from the file, but pending reads
* cannot be interleaved with other operations.
*/
[version = 1.1]
int32_t ReadToArray([in] PP_Resource file_io,
[in] int64_t offset,
[in] int32_t max_read_length,
[inout] PP_ArrayOutput output,
[in] PP_CompletionCallback callback);
};