NAME
sqlite3_commit_hook,
sqlite3_rollback_hook
—
Commit And Rollback Notification Callbacks
SYNOPSIS
void *
sqlite3_commit_hook(
sqlite3*,
int(*)(void*),
void*);
void *
sqlite3_rollback_hook(
sqlite3*,
void(*)(void *),
void*);
DESCRIPTION
The sqlite3_commit_hook() interface registers a callback function to be invoked
whenever a transaction is committed. Any callback set by a previous call to
sqlite3_commit_hook() for the same database connection is overridden. The
sqlite3_rollback_hook() interface registers a callback function to be invoked
whenever a transaction is rolled back. Any callback set by a previous call to
sqlite3_rollback_hook() for the same database connection is overridden. The
pArg argument is passed through to the callback. If the callback on a commit
hook function returns non-zero, then the commit is converted into a rollback.
The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions return
the P argument from the previous call of the same function on the same
database connection D, or NULL for the first call for each function on D.
The commit and rollback hook callbacks are not reentrant. The callback
implementation must not do anything that will modify the database connection
that invoked the callback. Any actions to modify the database connection must
be deferred until after the completion of the sqlite3_step() call that
triggered the commit or rollback hook in the first place. Note that running
any other SQL statements, including SELECT statements, or merely calling
sqlite3_prepare_v2() and sqlite3_step() will modify the database connections
for the meaning of "modify" in this paragraph.
Registering a NULL function disables the callback.
When the commit hook callback routine returns zero, the COMMIT operation is
allowed to continue normally. If the commit hook returns non-zero, then the
COMMIT is converted into a ROLLBACK. The rollback hook is invoked on a
rollback that results from a commit hook returning non-zero, just as it would
be with any other rollback.
For the purposes of this API, a transaction is said to have been rolled back if
an explicit "ROLLBACK" statement is executed, or an error or
constraint causes an implicit rollback to occur. The rollback callback is not
invoked if a transaction is automatically rolled back because the database
connection is closed.
See also the sqlite3_update_hook() interface.
SEE ALSO
sqlite3(3),
sqlite3_prepare(3),
sqlite3_step(3),
sqlite3_update_hook(3)