133 lines
5.0 KiB
Groff
133 lines
5.0 KiB
Groff
.Dd March 11, 2017
|
|
.Dt SQLITE3_PREUPDATE_HOOK 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm sqlite3_preupdate_hook ,
|
|
.Nm sqlite3_preupdate_old ,
|
|
.Nm sqlite3_preupdate_count ,
|
|
.Nm sqlite3_preupdate_depth ,
|
|
.Nm sqlite3_preupdate_new
|
|
.Nd The pre-update hook.
|
|
.Sh SYNOPSIS
|
|
.Ft void *
|
|
.Fo sqlite3_preupdate_hook
|
|
.Fa "sqlite3 *db"
|
|
.Fa "void(*xPreUpdate)( void *pCtx, sqlite3 *db, int op, char const *zDb, char const *zName, sqlite3_int64 iKey1, sqlite3_int64 iKey2 )"
|
|
.Fa "void* "
|
|
.Fc
|
|
.Ft int
|
|
.Fo sqlite3_preupdate_old
|
|
.Fa "sqlite3 *"
|
|
.Fa "int"
|
|
.Fa "sqlite3_value **"
|
|
.Fc
|
|
.Ft int
|
|
.Fo sqlite3_preupdate_count
|
|
.Fa "sqlite3 *"
|
|
.Fc
|
|
.Ft int
|
|
.Fo sqlite3_preupdate_depth
|
|
.Fa "sqlite3 *"
|
|
.Fc
|
|
.Ft int
|
|
.Fo sqlite3_preupdate_new
|
|
.Fa "sqlite3 *"
|
|
.Fa "int"
|
|
.Fa "sqlite3_value **"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
These interfaces are only available if SQLite is compiled using the
|
|
SQLITE_ENABLE_PREUPDATE_HOOK compile-time
|
|
option.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
The sqlite3_preupdate_count(D) interface
|
|
returns the number of columns in the row that is being inserted, updated,
|
|
or deleted.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
.Sh SEE ALSO
|
|
.Xr sqlite3 3 ,
|
|
.Xr sqlite3_value 3 ,
|
|
.Xr sqlite3_preupdate_hook 3 ,
|
|
.Xr sqlite3_update_hook 3 ,
|
|
.Xr sqlite3_value 3 ,
|
|
.Xr SQLITE_CREATE_INDEX 3
|