You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
337 lines
14 KiB
337 lines
14 KiB
/* 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.
|
|
*/
|
|
|
|
/* From ppb_file_io.idl modified Tue Oct 22 15:09:47 2013. */
|
|
|
|
#ifndef PPAPI_C_PPB_FILE_IO_H_
|
|
#define PPAPI_C_PPB_FILE_IO_H_
|
|
|
|
#include "ppapi/c/pp_array_output.h"
|
|
#include "ppapi/c/pp_bool.h"
|
|
#include "ppapi/c/pp_completion_callback.h"
|
|
#include "ppapi/c/pp_file_info.h"
|
|
#include "ppapi/c/pp_instance.h"
|
|
#include "ppapi/c/pp_macros.h"
|
|
#include "ppapi/c/pp_resource.h"
|
|
#include "ppapi/c/pp_stdint.h"
|
|
#include "ppapi/c/pp_time.h"
|
|
|
|
#define PPB_FILEIO_INTERFACE_1_0 "PPB_FileIO;1.0"
|
|
#define PPB_FILEIO_INTERFACE_1_1 "PPB_FileIO;1.1"
|
|
#define PPB_FILEIO_INTERFACE PPB_FILEIO_INTERFACE_1_1
|
|
|
|
/**
|
|
* @file
|
|
* This file defines the API to create a file i/o object.
|
|
*/
|
|
|
|
|
|
/**
|
|
* @addtogroup Enums
|
|
* @{
|
|
*/
|
|
/**
|
|
* The PP_FileOpenFlags enum contains file open constants.
|
|
*/
|
|
typedef enum {
|
|
/** Requests read access to a file. */
|
|
PP_FILEOPENFLAG_READ = 1 << 0,
|
|
/**
|
|
* Requests write access to a file. May be combined with
|
|
* <code>PP_FILEOPENFLAG_READ</code> 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
|
|
* <code>PP_FILEOPENFLAG_EXCLUSIVE</code> 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. <code>PP_FILEOPENFLAG_WRITE</code> must also be specified.
|
|
*/
|
|
PP_FILEOPENFLAG_TRUNCATE = 1 << 3,
|
|
/**
|
|
* Requests that the file is created when this flag is combined with
|
|
* <code>PP_FILEOPENFLAG_CREATE</code>. If this flag is specified, and the
|
|
* file already exists, then the FileIO::Open() call will fail.
|
|
*/
|
|
PP_FILEOPENFLAG_EXCLUSIVE = 1 << 4,
|
|
/**
|
|
* Requests write access to a file, but writes will always occur at the end of
|
|
* the file. Mututally exclusive with <code>PP_FILEOPENFLAG_WRITE</code>.
|
|
*
|
|
* This is only supported in version 1.2 (Chrome 29) and later.
|
|
*/
|
|
PP_FILEOPENFLAG_APPEND = 1 << 5
|
|
} PP_FileOpenFlags;
|
|
PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_FileOpenFlags, 4);
|
|
/**
|
|
* @}
|
|
*/
|
|
|
|
/**
|
|
* @addtogroup Interfaces
|
|
* @{
|
|
*/
|
|
/**
|
|
* The <code>PPB_FileIO</code> struct is used to operate on a regular file
|
|
* (PP_FileType_Regular).
|
|
*/
|
|
struct PPB_FileIO_1_1 {
|
|
/**
|
|
* Create() creates a new FileIO object.
|
|
*
|
|
* @param[in] instance A <code>PP_Instance</code> identifying the instance
|
|
* with the file.
|
|
*
|
|
* @return A <code>PP_Resource</code> corresponding to a FileIO if
|
|
* successful or 0 if the module is invalid.
|
|
*/
|
|
PP_Resource (*Create)(PP_Instance instance);
|
|
/**
|
|
* IsFileIO() determines if the provided resource is a FileIO.
|
|
*
|
|
* @param[in] resource A <code>PP_Resource</code> corresponding to a FileIO.
|
|
*
|
|
* @return <code>PP_TRUE</code> if the resource is a
|
|
* <code>PPB_FileIO</code>, <code>PP_FALSE</code> if the resource is
|
|
* invalid or some type other than <code>PPB_FileIO</code>.
|
|
*/
|
|
PP_Bool (*IsFileIO)(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 <code>PP_FileOpenFlags</code>
|
|
* 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 <code>PP_Resource</code> corresponding to a
|
|
* FileIO.
|
|
* @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
|
|
* reference.
|
|
* @param[in] open_flags A bit-mask of the <code>PP_FileOpenFlags</code>
|
|
* values.
|
|
* @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
|
|
* completion of Open().
|
|
*
|
|
* @return An int32_t containing an error code from <code>pp_errors.h</code>.
|
|
*/
|
|
int32_t (*Open)(PP_Resource file_io,
|
|
PP_Resource file_ref,
|
|
int32_t open_flags,
|
|
struct 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 <code>PP_Resource</code> corresponding to a
|
|
* FileIO.
|
|
* @param[out] info The <code>PP_FileInfo</code> structure representing all
|
|
* information about the file.
|
|
* @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
|
|
* completion of Query(). <code>info</code> must remain valid until after the
|
|
* callback runs. If you pass a blocking callback, <code>info</code> must
|
|
* remain valid until after Query() returns.
|
|
*
|
|
* @return An int32_t containing an error code from <code>pp_errors.h</code>.
|
|
* 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)(PP_Resource file_io,
|
|
struct PP_FileInfo* info,
|
|
struct 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 <code>PP_Resource</code> 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 <code>PP_CompletionCallback</code> to be called upon
|
|
* completion of Touch().
|
|
*
|
|
* @return An int32_t containing an error code from <code>pp_errors.h</code>.
|
|
* 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)(PP_Resource file_io,
|
|
PP_Time last_access_time,
|
|
PP_Time last_modified_time,
|
|
struct 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.
|
|
* The FileIO object must have been opened with read access.
|
|
*
|
|
* ReadToArray() is preferred to Read() when doing asynchronous operations.
|
|
*
|
|
* @param[in] file_io A <code>PP_Resource</code> 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
|
|
* <code>offset</code>.
|
|
* @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
|
|
* completion of Read(). <code>buffer</code> must remain valid until after
|
|
* the callback runs. If you pass a blocking callback, <code>buffer</code>
|
|
* must remain valid until after Read() returns.
|
|
*
|
|
* @return The number of bytes read or an error code from
|
|
* <code>pp_errors.h</code>. 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)(PP_Resource file_io,
|
|
int64_t offset,
|
|
char* buffer,
|
|
int32_t bytes_to_read,
|
|
struct 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 <code>PP_Resource</code> 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
|
|
* <code>offset</code>.
|
|
* @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
|
|
* completion of Write().
|
|
*
|
|
* @return The number of bytes written or an error code from
|
|
* <code>pp_errors.h</code>. 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)(PP_Resource file_io,
|
|
int64_t offset,
|
|
const char* buffer,
|
|
int32_t bytes_to_write,
|
|
struct 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 <code>PP_Resource</code> corresponding to a file
|
|
* FileIO.
|
|
* @param[in] length The length of the file to be set.
|
|
* @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
|
|
* completion of SetLength().
|
|
*
|
|
* @return An int32_t containing an error code from <code>pp_errors.h</code>.
|
|
* 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)(PP_Resource file_io,
|
|
int64_t length,
|
|
struct 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 <code>PP_Resource</code> corresponding to a file
|
|
* FileIO.
|
|
* @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
|
|
* completion of Flush().
|
|
*
|
|
* @return An int32_t containing an error code from <code>pp_errors.h</code>.
|
|
* 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)(PP_Resource file_io, struct PP_CompletionCallback callback);
|
|
/**
|
|
* Close() cancels any IO that may be pending, and closes the FileIO object.
|
|
* Any pending callbacks will still run, reporting
|
|
* <code>PP_ERROR_ABORTED</code> if pending IO was interrupted. It is not
|
|
* valid to call Open() again after a call to this method.
|
|
* <strong>Note:</strong> 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 <code>PP_Resource</code> corresponding to a file
|
|
* FileIO.
|
|
*/
|
|
void (*Close)(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. The FileIO object must have been
|
|
* opened with read access.
|
|
*
|
|
* @param[in] file_io A <code>PP_Resource</code> 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
|
|
* <code>offset</code>.
|
|
* @param[in] output A <code>PP_ArrayOutput</code> to hold the output data.
|
|
* @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
|
|
* completion of ReadToArray().
|
|
*
|
|
* @return The number of bytes read or an error code from
|
|
* <code>pp_errors.h</code>. 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.
|
|
*/
|
|
int32_t (*ReadToArray)(PP_Resource file_io,
|
|
int64_t offset,
|
|
int32_t max_read_length,
|
|
struct PP_ArrayOutput* output,
|
|
struct PP_CompletionCallback callback);
|
|
};
|
|
|
|
typedef struct PPB_FileIO_1_1 PPB_FileIO;
|
|
|
|
struct PPB_FileIO_1_0 {
|
|
PP_Resource (*Create)(PP_Instance instance);
|
|
PP_Bool (*IsFileIO)(PP_Resource resource);
|
|
int32_t (*Open)(PP_Resource file_io,
|
|
PP_Resource file_ref,
|
|
int32_t open_flags,
|
|
struct PP_CompletionCallback callback);
|
|
int32_t (*Query)(PP_Resource file_io,
|
|
struct PP_FileInfo* info,
|
|
struct PP_CompletionCallback callback);
|
|
int32_t (*Touch)(PP_Resource file_io,
|
|
PP_Time last_access_time,
|
|
PP_Time last_modified_time,
|
|
struct PP_CompletionCallback callback);
|
|
int32_t (*Read)(PP_Resource file_io,
|
|
int64_t offset,
|
|
char* buffer,
|
|
int32_t bytes_to_read,
|
|
struct PP_CompletionCallback callback);
|
|
int32_t (*Write)(PP_Resource file_io,
|
|
int64_t offset,
|
|
const char* buffer,
|
|
int32_t bytes_to_write,
|
|
struct PP_CompletionCallback callback);
|
|
int32_t (*SetLength)(PP_Resource file_io,
|
|
int64_t length,
|
|
struct PP_CompletionCallback callback);
|
|
int32_t (*Flush)(PP_Resource file_io, struct PP_CompletionCallback callback);
|
|
void (*Close)(PP_Resource file_io);
|
|
};
|
|
/**
|
|
* @}
|
|
*/
|
|
|
|
#endif /* PPAPI_C_PPB_FILE_IO_H_ */
|
|
|
|
|