BFILE C/C++ Objects and Functions

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:

sqlite3_column_bfile

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.

sqlite3_bfile_open

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.

sqlite3_bfile_close

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.

sqlite3_bfile_is_open

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.

sqlite3_bfile_read

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.

Note

The size of the BFILE can be determined using the sqlite3_bfile_size function.

sqlite3_bfile_file_exists

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.

sqlite3_bfile_size

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.

sqlite3_bfile_final

int
sqlite3_bfile_final(sqlite3_bfile *pBfile);

Frees a BFILE handle.

On success, SQLITE_OK is returned. Otherwise, SQLITE_ERROR is returned.