NAME
sqlite3_preupdate_hook,
sqlite3_preupdate_old,
sqlite3_preupdate_count,
sqlite3_preupdate_depth,
sqlite3_preupdate_new —
The
pre-update hook.
SYNOPSIS
void *
sqlite3_preupdate_hook(
sqlite3 *db,
void(*xPreUpdate)( void *pCtx, sqlite3 *db, int op, char const
*zDb, char const *zName, sqlite3_int64 iKey1, sqlite3_int64 iKey2 ),
void* );
int
sqlite3_preupdate_old(
sqlite3 *,
int,
sqlite3_value **);
int
sqlite3_preupdate_count(
sqlite3 *);
int
sqlite3_preupdate_depth(
sqlite3 *);
int
sqlite3_preupdate_new(
sqlite3 *,
int,
sqlite3_value **);
DESCRIPTION
These interfaces are only available if SQLite is compiled using the
SQLITE_ENABLE_PREUPDATE_HOOK compile-time option.
The sqlite3_preupdate_hook() interface registers a callback function that is
invoked prior to each INSERT, UPDATE, and DELETE operation on a database
table. At most one preupdate hook may be registered at a time on a single
database connection; each call to sqlite3_preupdate_hook() overrides the
previous setting. The preupdate hook is disabled by invoking
sqlite3_preupdate_hook() with a NULL pointer as the second parameter. The
third parameter to sqlite3_preupdate_hook() is passed through as the first
parameter to callbacks.
The preupdate hook only fires for changes to real database tables; the preupdate
hook is not invoked for changes to virtual tables or to system tables like
sqlite_master or sqlite_stat1.
The second parameter to the preupdate callback is a pointer to the database
connection that registered the preupdate hook. The third parameter to the
preupdate callback is one of the constants SQLITE_INSERT, SQLITE_DELETE, or
SQLITE_UPDATE to identify the kind of update operation that is about to occur.
The fourth parameter to the preupdate callback is the name of the database
within the database connection that is being modified. This will be
"main" for the main database or "temp" for TEMP tables or
the name given after the AS keyword in the ATTACH statement for attached
databases. The fifth parameter to the preupdate callback is the name of the
table that is being modified.
For an UPDATE or DELETE operation on a rowid table, the sixth parameter passed
to the preupdate callback is the initial rowid of the row being modified or
deleted. For an INSERT operation on a rowid table, or any operation on a
WITHOUT ROWID table, the value of the sixth parameter is undefined. For an
INSERT or UPDATE on a rowid table the seventh parameter is the final rowid
value of the row being inserted or updated. The value of the seventh parameter
passed to the callback function is not defined for operations on WITHOUT ROWID
tables, or for INSERT operations on rowid tables.
The sqlite3_preupdate_old(), sqlite3_preupdate_new(), sqlite3_preupdate_count(),
and sqlite3_preupdate_depth() interfaces provide additional information about
a preupdate event. These routines may only be called from within a preupdate
callback. Invoking any of these routines from outside of a preupdate callback
or with a database connection pointer that is different from the one supplied
to the preupdate callback results in undefined and probably undesirable
behavior.
The sqlite3_preupdate_count(D) interface returns the number of columns in the
row that is being inserted, updated, or deleted.
The sqlite3_preupdate_old(D,N,P) interface writes into P a pointer to a
protected sqlite3_value that contains the value of the Nth column of the table
row before it is updated. The N parameter must be between 0 and one less than
the number of columns or the behavior will be undefined. This must only be
used within SQLITE_UPDATE and SQLITE_DELETE preupdate callbacks; if it is used
by an SQLITE_INSERT callback then the behavior is undefined. The sqlite3_value
that P points to will be destroyed when the preupdate callback returns.
The sqlite3_preupdate_new(D,N,P) interface writes into P a pointer to a
protected sqlite3_value that contains the value of the Nth column of the table
row after it is updated. The N parameter must be between 0 and one less than
the number of columns or the behavior will be undefined. This must only be
used within SQLITE_INSERT and SQLITE_UPDATE preupdate callbacks; if it is used
by an SQLITE_DELETE callback then the behavior is undefined. The sqlite3_value
that P points to will be destroyed when the preupdate callback returns.
The sqlite3_preupdate_depth(D) interface returns 0 if the preupdate callback was
invoked as a result of a direct insert, update, or delete operation; or 1 for
inserts, updates, or deletes invoked by top-level triggers; or 2 for changes
resulting from triggers called by top-level triggers; and so forth.
SEE ALSO
sqlite3(3),
sqlite3_value(3),
sqlite3_preupdate_hook(3),
sqlite3_update_hook(3),
sqlite3_value(3),
SQLITE_CREATE_INDEX(3)