The BFILE extension can optionally make available to you some additional C language data types and functions for use with the SQLite C/C++ interface. These are available to you only if you take the proper steps when you compile Berkeley DB. See the Berkeley DB Installation and Build Guide for more information.
Once enabled, the BFILE C extension makes the following new structure available to you:
typedef struct sqlite3_bfile sqlite3_bfile;
This structure serves as the BFILE handle when you are using the BFILE extension along with the SQLite C/C++ interface.
In addition to the new structure, you can also use the following new C functions:
int
sqlite3_column_bfile(sqlite3_stmt *pStmt, int iCol,
sqlite3_bfile **ppBfile);
Returns a result set from a query against a column of type BFILE.
On success, SQLITE_OK is returned and
the new BFILE handle is written to
ppBfile. Otherwise,
SQLITE_ERROR is returned.
Parameters are:
pStmt
Pointer to the prepared statement that the function
is evaluating. The statement is created
using sqlite3_prepare_v2()
or one of its variants.
If this statement does not point to a valid row, the result is undefined.
iCol
Index of the column for which information should be
returned. The left-most column of the result set
is index 0. Use
sqlite3_column_count() to discover
the number of columns in the result set.
If the column index is out of range, the result is undefined.
ppBfile
The BFILE handle that you are using for the query.
This pointer is valid only until
sqlite3_step(),
sqlite3_reset() or
sqlite3_finalize() have been
called.
The memory space used to hold this handle is freed by
sqlite3_bfile_final
Do not pass these pointers to sqlite3_free().
This function can be called successfully only if all of the following conditions are true. If any of the following are not true, the result is undefined:
The most recent call to
sqlite3_step() has returned
SQLITE_ROW.
Neither sqlite3_reset() nor
sqlite3_finalize() have been
called since the last time
sqlite3_step() was called.
sqlite3_step(),
sqlite3_reset() or
sqlite3_finalize() have not been
called from a different thread while this routine
is pending.
int sqlite3_bfile_open(sqlite3_bfile *pBfile);
Opens a file for incremental read.
On success, SQLITE_OK is returned.
Otherwise, SQLITE_ERROR is returned.
To avoid a resource leak, every opened BFILE handle should
eventually be closed with the
sqlite3_bfile_close
function. Note that pBfile
is always initialized such that it is always safe to invoke
sqlite_bfile_close() against it,
regardless of the success or failure of this function.
int sqlite3_bfile_close(sqlite3_bfile *pBfile);
Closes an open BFILE handle. The BFILE is closed unconditionally. Even if this function returns an error, the BFILE is still closed.
Calling this routine with a null pointer (such as would be returned by failed call to sqlite3_column_bfile()) is a harmless non-operation.
On success, SQLITE_OK is returned.
Otherwise, SQLITE_ERROR is returned.
int sqlite3_bfile_is_open(sqlite3_bfile *pBfile, int *open);
Checks whether a BFILE handle is open. The
open parameter is set to 1 if the file
is open, otherwise it is 0.
On success, SQLITE_OK is returned.
Otherwise, SQLITE_ERROR is returned.
int
sqlite3_bfile_read(sqlite3_bfile *pBfile, void *oBuff, int nSize,
int iOffset, int *nRead);
This function is used to read data from an opened BFILE handle into a caller-supplied buffer.
On success, SQLITE_OK is returned, the
data that has been read is written to the output buffer,
oBuff,
and the amount of data written to the buffer is recorded in
nRead.
Otherwise, SQLITE_ERROR is returned.
Parameters are:
pBfile
The BFILE handle from which the data is read.
This function only works on a BFILE handle which has been created by a prior successful call to sqlite3_bfile_open and which has not been closed by sqlite3_bfile_close. Passing any other pointer in to this function results in undefined and probably undesirable behavior.
oBuff
The buffer used to contain the data that is read from pBfile. It must be at least nSize bytes in size.
nSize
The amount of data, in bytes, to read from the BFILE.
iOffset
The offset from the beginning of the file where the read operation is to begin.
nRead
Contains the amount of data, in bytes, actually written to buffer oBuff once the read operation is completed.
The size of the BFILE can be determined using the sqlite3_bfile_size function.
int sqlite3_bfile_file_exists(sqlite3_bfile *pBfile, int *exist);
Checks whether a BFILE exists. The
exists parameter is set to 1 if the file
is exists, otherwise it is 0.
On success, SQLITE_OK is returned.
Otherwise, SQLITE_ERROR is returned.
int sqlite3_bfile_size(sqlite3_bfile *pBfile, off_t *size);
Returns the size of the BFILE, in bytes.
On success, SQLITE_OK is returned, and
size is set to the size of
the BFILE, in bytes.
Otherwise, SQLITE_ERROR is returned.
This function only works on a BFILE handle which has been created by a prior successful call to sqlite3_column_bfile and which has not been finalized by sqlite3_bfile_final. Passing any other pointer in to this function results in undefined and probably undesirable behavior.