Small. Fast. Reliable.
Choose any three.

SQLite C Interface

Write Data Into A BLOB Incrementally

int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);

This function is used to write data into an open BLOB handle from a caller-supplied buffer. N bytes of data are copied from the buffer Z into the open BLOB, starting at offset iOffset.

If the BLOB handle passed as the first argument was not opened for writing (the flags parameter to sqlite3_blob_open() was zero), this function returns SQLITE_READONLY.

This function may only modify the contents of the BLOB; it is not possible to increase the size of a BLOB using this API. If offset iOffset is less than N bytes from the end of the BLOB, SQLITE_ERROR is returned and no data is written. If N is less than zero SQLITE_ERROR is returned and no data is written.

An attempt to write to an expired BLOB handle fails with an error code of SQLITE_ABORT. Writes to the BLOB that occurred before the BLOB handle expired are not rolled back by the expiration of the handle, though of course those changes might have been overwritten by the statement that expired the BLOB handle or by other independent statements.

On success, SQLITE_OK is returned. Otherwise, an error code or an extended error code is returned.

Invariants:

H17873 A successful invocation of sqlite3_blob_write(P,Z,N,X) shall write N bytes of data from buffer Z into the BLOB referenced by BLOB handle P beginning at offset X into the BLOB.
H17874 In the absence of other overridding changes, the changes written to a BLOB by sqlite3_blob_write() shall remain in effect after the associated BLOB handle expires.
H17875 If the BLOB handle P was opened for reading only then an invocation of sqlite3_blob_write(P,Z,N,X) shall leave the referenced BLOB unchanged and return SQLITE_READONLY.
H17876 If the size of the BLOB referenced by BLOB handle P is less than N+X bytes then sqlite3_blob_write(P,Z,N,X) shall leave the BLOB unchanged and return SQLITE_ERROR.
H17877 If the BLOB handle P is expired and X and N are within bounds then sqlite3_blob_read(P,Z,N,X) shall leave the BLOB unchanged and return SQLITE_ABORT.
H17879 If X or N are less than zero then sqlite3_blob_write(P,Z,N,X) shall leave the BLOB referenced by BLOB handle P unchanged and return SQLITE_ERROR.
H17882 The sqlite3_blob_write(P,Z,N,X) interface shall return SQLITE_OK if N bytes where successfully written into the BLOB.
H17885 If the requested write could not be completed, the sqlite3_blob_write(P,Z,N,X) interface shall return an appropriate error code or extended error code.
H17888 If an error occurs during evaluation of sqlite3_blob_write(D,...) then subsequent calls to sqlite3_errcode(D), sqlite3_extended_errcode(), sqlite3_errmsg(D), and sqlite3_errmsg16(D) shall return information appropriate for that error.

See also lists of Objects, Constants, and Functions.


This page last modified 2008/12/09 18:44:04 UTC