The pre-update hook

The pre-update hook.

#if defined(SQLITE_ENABLE_PREUPDATE_HOOK)
void *sqlite3_preupdate_hook(
  sqlite3 *db,
  void(*xPreUpdate)(
    void *pCtx,                   /* Copy of third arg to preupdate_hook() */
    sqlite3 *db,                  /* Database handle */
    int op,                       /* SQLITE_UPDATE, DELETE or INSERT */
    char const *zDb,              /* Database name */
    char const *zName,            /* Table name */
    sqlite3_int64 iKey1,          /* Rowid of row about to be deleted/updated */
    sqlite3_int64 iKey2           /* New rowid value (for a rowid UPDATE) */
  ),
  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 **);
#endif

这些接口只有在使用SQLITE_ENABLE_PREUPDATE_HOOK编译时选项编译SQLite时才可用。

sqlite3_preupdate_hook()接口注册一个回调函数，该函数在数据库表上的每个INSERT，UPDATE和DELETE操作之前调用。一次只能在一个数据库连接上注册一个preupdate钩子; 每次调用sqlite3_preupdate_hook()都会覆盖之前的设置。通过用NULL指针调用sqlite3_preupdate_hook()作为第二个参数来禁用preupdate钩子。sqlite3_preupdate_hook()的第三个参数作为第一个参数传递给回调函数。

preupdate钩子只会触发对实际数据库表的更改; preupdate挂钩不会被调用以更改虚拟表或系统表，如sqlite_master或sqlite_stat1。

preupdate回调的第二个参数是指向注册preupdate钩子的数据库连接的指针。preupdate回调函数的第三个参数是常量SQLITE_INSERT，SQLITE_DELETE或SQLITE_UPDATE之一，用于标识即将发生的更新操作的种类。preupdate回调的第四个参数是正在修改的数据库连接中的数据库名称。对于主数据库，这将是“主要”，对于附加数据库，这将是TEMP表的“主要”或ATTACH语句中AS关键字后给出的名称。preupdate回调的第五个参数是正在修改的表的名称。

对于rowid表上的UPDATE或DELETE操作，传递给preupdate回调的第六个参数是被修改或删除的行的初始rowid。对于rowid表上的INSERT操作或WITHOUT ROWID表上的任何操作，第六个参数的值是未定义的。对于rowid表上的INSERT或UPDATE，第七个参数是插入或更新的行的最终rowid值。传递给回调函数的第七个参数的值未针对WITHOUT ROWID表上的操作或rowid表上的INSERT操作进行定义。

sqlite3_preupdate_old()，sqlite3_preupdate_new()，sqlite3_preupdate_count()和sqlite3_preupdate_depth()接口提供有关preupdate事件的其他信息。这些例程只能在preupdate回调中调用。从preupdate回调以外的数据库连接指针或与提供给preupdate回调函数的数据库连接指针不同的这些例程中调用任何这些例程都会导致未定义且可能不需要的行为。

sqlite3_preupdate_count(D)接口返回正在插入，更新或删除的行的列数。

sqlite3_preupdate_old(D，N，P)接口向P写入一个指向受保护的sqlite3_value的指针，该sqlite3_value在更新之前包含表行第N列的值。N参数必须介于0和1之间，否则行为将不确定。这只能在SQLITE_UPDATE和SQLITE_DELETE preupdate回调中使用; 如果它被SQLITE_INSERT回调使用，那么行为是不确定的。P指向的sqlite3_value将在preupdate回调返回时被销毁。

sqlite3_preupdate_new(D，N，P)接口向P写入一个指向受保护的sqlite3_value的指针，该sqlite3_value在更新后包含表行第N列的值。N参数必须介于0和1之间，否则行为将不确定。这只能在SQLITE_INSERT和SQLITE_UPDATE预更新回调中使用; 如果它被SQLITE_DELETE回调使用，那么行为是未定义的。P指向的sqlite3_value将在preupdate回调返回时被销毁。

如果由于直接插入，更新或删除操作而调用preupdate回调，sqlite3_preupdate_depth(D)接口返回0; 或1表示由顶级触发器调用的插入，更新或删除操作; 或2由顶级触发器调用触发器引起的更改; 等等。