SQLiteC/C++接口详细介绍之sqlite3类（十四）

返回目录：SQLite—免费开源数据库系列文章目录

上一篇：SQLiteC/C++接口详细介绍之sqlite3类（十三）

下一篇：SQLiteC/C++接口详细介绍之sqlite3类（十五）

43.sqlite3_preupdate_hook

sqlite3_preupdate_hook函数用于注册一个回调函数，当执行UPDATE、INSERT、DELETE操作时，此回调函数会在每一行变更之前被调用。该函数的原型如下：

void sqlite3_preupdate_hook(
  sqlite3 *db,
  void *pArg,
  int iCmd,
  char const *zDb,
  char const *zName,
  sqlite3_int64 arg1,
  sqlite3_int64 arg2,
  int arg3
);

该函数的参数说明如下：

- db: 数据库连接句柄。
- pArg: 提供给回调函数使用的用户指针。
- iCmd: 修改命令类型，值为SQLITE_INSERT、SQLITE_UPDATE或SQLITE_DELETE。
- zDb和zName: 数据库名和表名。
- arg1、arg2和arg3: 提供详细信息的附加参数。

下面是一个示例，在执行UPDATE、INSERT、DELETE操作之前，输出被更改的列的值：

#include <sqlite3.h>
#include <stdio.h>
static void preupdate_callback(
    sqlite3 *db,  // 数据库连接句柄
    void *pArg,   // 用户指针
    int iCmd,     // 修改命令类型
    char const *zDb,  // 数据库名
    char const *zName, // 表名
    sqlite3_int64 arg1,  // 行ID
    sqlite3_int64 arg2,  // 新行ID
    int arg3             // 列ID
) {
    if (iCmd == SQLITE_UPDATE) {
        printf("UPDATE table %s.%s: (id=%lld) %d -> %d\n", zDb, zName, arg1,
            *((int*)arg2 + arg3), *((int*)arg1 + arg3));
    } else if (iCmd == SQLITE_INSERT) {
        printf("INSERT table %s.%s: (id=%lld)\n", zDb, zName, arg1);
    } else if (iCmd == SQLITE_DELETE) {
        printf("DELETE table %s.%s: (id=%lld)\n", zDb, zName, arg1);
    }
}
int main() {
    sqlite3 *db;
    sqlite3_open(":memory:", &db);
    sqlite3_exec(db, "CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)", NULL, NULL, NULL);
    sqlite3_preupdate_hook(db, preupdate_callback, NULL);
    sqlite3_exec(db, "INSERT INTO test (id, value) VALUES (1, 'hello')", NULL, NULL, NULL);
    sqlite3_exec(db, "UPDATE test SET value = 'world' WHERE id = 1", NULL, NULL, NULL);
    sqlite3_exec(db, "DELETE FROM test WHERE id = 1", NULL, NULL, NULL);
    sqlite3_close(db);
    return 0;
}

输出结果为：

INSERT table main.test: (id=1)
UPDATE table main.test: (id=1) hello -> world
DELETE table main.test: (id=1)

44.sqlite3_preupdate_new

sqlite3_preupdate_new函数用于向UPDATE事件中添加一个新的行。通常情况下，UPDATE事件会更新一个已经存在的行，但有时候需要添加一行新的数据，并以此替换原来的行。例如，当更新一行数据时，如果该行数据不存在，有时需要新增一行数据。

该函数的原型如下：

int sqlite3_preupdate_new(
  sqlite3 *db,
  int op,
  const char *zDb,
  const char *zName,
  sqlite_int64 iKey
);

该函数的参数说明如下：

- db: 数据库连接句柄。
- op: 操作类型，取值为SQLITE_INSERT或SQLITE_UPDATE。
- zDb和zName: 数据库名和表名。
- iKey: 新行的主键值。

该函数必须在sqlite3_preupdate_hook回调函数中调用，并在调用sqlite3_preupdate_step()之前被调用。下面是一个示例，该示例在UPDATE事件中新增一个行数据：

#include <sqlite3.h>
#include <stdio.h>
static void preupdate_callback(
    sqlite3 *db,  // 数据库连接句柄
    void *pArg,   // 用户指针
    int iCmd,     // 修改命令类型
    char const *zDb,  // 数据库名
    char const *zName, // 表名
    sqlite3_int64 arg1,  // 行ID
    sqlite3_int64 arg2,  // 新行ID
    int arg3             // 列ID
) {
    if (iCmd == SQLITE_UPDATE) {
        const char *value = "new value";
        sqlite3_preupdate_new(db, SQLITE_INSERT, zDb, zName, arg2);
        sqlite3_preupdate_set(db, value);
        sqlite3_preupdate_column_name(db, "value");
    }
}
int main() {
    sqlite3 *db;
    sqlite3_open(":memory:", &db);
    sqlite3_exec(db, "CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)", NULL, NULL, NULL);
    sqlite3_preupdate_hook(db, preupdate_callback, NULL);
    sqlite3_exec(db, "UPDATE test SET value = 'world' WHERE id = 1", NULL, NULL, NULL);
    sqlite3_close(db);
    return 0;
}

该示例实现了当UPDATE语句在表test中更新主键值为1的数据时，如果该行数据不存在，则新增一行数据，并将value列的值设置为"new value"。

注意:在调用sqlite3_preupdate_new()函数之后，必须通过sqlite3_preupdate_set()设置新插入行的数据，这样才能正常插入数据。

45.sqlite3_preupdate_old

sqlite3_preupdate_old函数用于获取UPDATE事件中的旧行数据。当执行UPDATE语句时，旧行数据需要在sqlite3_preupdate_hook回调函数中使用，例如用于记录更改日志或在更新前对比新旧数据等。

该函数的原型如下：

const void *sqlite3_preupdate_old(
  sqlite3 *db,
  int op,
  const char *zDb,
  const char *zName,
  sqlite_int64 iKey
);

该函数的参数说明如下：

- db: 数据库连接句柄。
- op: 操作类型，取值为SQLITE_INSERT或SQLITE_UPDATE。
- zDb和zName: 数据库名和表名。
- iKey: 主键值。

该函数必须在sqlite3_preupdate_hook回调函数中调用，并在调用sqlite3_preupdate_step()之前被调用。返回值是一个指向旧行数据的指针，如果该行不存在，则返回NULL。

下面是一个示例，该示例在UPDATE事件中获取旧行数据并输出：

#include <sqlite3.h>
#include <stdio.h>
static void preupdate_callback(
    sqlite3 *db,  // 数据库连接句柄
    void *pArg,   // 用户指针
    int iCmd,     // 修改命令类型
    char const *zDb,  // 数据库名
    char const *zName, // 表名
    sqlite3_int64 arg1,  // 行ID
    sqlite3_int64 arg2,  // 新行ID
    int arg3             // 列ID
) {
    if (iCmd == SQLITE_UPDATE) {
        const void *old_data = sqlite3_preupdate_old(db, SQLITE_UPDATE, zDb, zName, arg1);
        if (old_data) {
            printf("old data: id=%lld, value=%s\n", arg1, (const char*)sqlite3_value_text((sqlite3_value*)old_data + 1));
        } else {
            printf("old data not found: id=%lld\n", arg1);
        }
    }
}
int main() {
    sqlite3 *db;
    sqlite3_open(":memory:", &db);
    sqlite3_exec(db, "CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)", NULL, NULL, NULL);
    sqlite3_preupdate_hook(db, preupdate_callback, NULL);
    sqlite3_exec(db, "INSERT INTO test (id, value) VALUES (1, 'hello')", NULL, NULL, NULL);
    sqlite3_exec(db, "UPDATE test SET value = 'world' WHERE id = 1", NULL, NULL, NULL);
    sqlite3_exec(db, "DELETE FROM test WHERE id = 1", NULL, NULL, NULL);
    sqlite3_close(db);
    return 0;
}

该示例在UPDATE事件中获取id为1的旧行数据，并输出id和value的值。如果旧行数据不存在，则输出"old data not found"。需要注意的是，在sqlite3_value_text()函数中传入的参数是一个指向sqlite3_value结构体的指针。

46.sqlite3_progress_handler

sqlite3_progress_handler函数用于安装一个进度回调函数，用于检查长时间运行的语句的运行时间，并防止其耗费太多的CPU。如果在指定的运行时间内没有回调函数，则sqlite3_progress_handler将返回非零值，从而终止长时间运行的语句。

函数原型：
void sqlite3_progress_handler(sqlite3 *db, int iInterval, int(*xCallback)(void*), void *pArg);
函数参数说明：

- db：需要监听的数据库。
- iInterval：回调函数被调用的时间间隔，以毫秒为单位。如果iInterval为0，则将调用回调函数，在执行每个数据库操作之前检查是否需要中止操作。如果iInterval不为0，则在执行每个数据库操作之前等待iInterval毫秒，并且在时间到期时调用回调函数以检查操作是否应继续。
- xCallback：回调函数指针，指向一个返回整数的函数。如果回调函数返回非零值，则长时间运行的语句将被终止。如果回调函数返回零值，则长时间运行的语句将继续运行。
- pArg：传递给回调函数的用户指针。

下面是一个简单的示例：

#include <sqlite3.h>
#include <stdio.h>
#include <unistd.h>

static int progress_callback(void *pArg) {
printf("progress_callback\n");
return 0;
}

int main() {
sqlite3 *db;
sqlite3_open(":memory:", &db);
sqlite3_progress_handler(db, 1000, progress_callback, NULL);
sqlite3_exec(db, "CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)", NULL, NULL, NULL);
sqlite3_exec(db, "INSERT INTO test VALUES (1, 'hello')", NULL, NULL, NULL);
sleep(2);
sqlite3_finalize(db);
return 0;
}
该示例在打开数据库连接后安装了一个回调函数，在操作一个语句时，程序会暂停2秒。在这个暂停的过程中，回调函数每隔1秒钟被调用一次，当到达1秒和2秒时，由于回调函数返回0，长时间运行的操作仍会继续运行。在操作完成之后，关闭数据库连接。