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

 快速跳转文章列表：SQLite—系列文章目录

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

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

编写不易，有用的朋友点个赞或加粉一下万分感谢！300名内回关！

3.sqlite3类的成员函数sqlite3_autovacuum_pages函数

函数形式： 

int sqlite3_autovacuum_pages(
  sqlite3 *db,
  unsigned int(*)(void*,const char*,unsigned int,unsigned int,unsigned int),
  void*,
  void(*)(void*)
);

用于设置自动VACUUM时，保留的未使用页的最小数量。VACUUM是SQLite中的一个操作，用于减小由于删除和更新操作而产生的数据库文件大小。在执行VACUUM时，SQLite查询数据库中的所有对象，并将其重新组织为较小的部分，以减小文件大小并提高性能。当VACUUM完成时，空闲页被释放并添加到可用页面池中，以备后续使用。
sqlite3_autovacuum_pages函数的作用是设置自动执行VACUUM操作时保留的未使用页面的最小数目。VACUUM操作完成后，自动VACUUM机制可以确定保留多少页作为未使用页面，并用于后续的插入操作，以避免频繁的文件增长和收缩。SQLite通常不需要手动执行VACUUM操作，因为它会自动执行此操作。不过，如果需要手动执行VACUUM操作，可以使用该函数设置保留未使用页面的最小数量。

sqlite3_autovacuum_pages(D,C,P,X)接口注册了一个回调函数C，该函数在每次自动执行数据库文件的VACUUM操作之前被调用。回调函数被传递一个通用数据指针的副本（P），正在执行VACUUM操作的数据库附加的模式名称，数据库文件大小（以页为单位），免费页面数以及每个页面的字节数。回调函数应该返回应由自动VACUUM操作移除的免费页数。如果回调函数返回零，则不执行VACUUM操作。如果返回的值大于或等于空闲页面的数量，则进行完整的VACUUM操作。

如果多个已附加的数据库文件作为事务提交的一部分进行了修改，则自动VACUUM页面回调会针对每个文件分别调用。

回调函数不支持线程重入。回调函数不应尝试调用其他SQLite接口。如果这样做，可能会发生错误，包括分段错误和损坏的数据库文件。回调函数应该是一个简单的函数，对其输入参数进行一些算术操作并返回结果。

sqlite3_autovacuum_pages(D,C,P,X)中的X参数是P参数的可选析构函数。如果X不为NULL，则在数据库连接关闭或回调被其他sqlite3_autovacuum_pages()调用覆盖时，将调用X(P)。

每个数据库连接只有一个自动VACUUM页面回调。每次对sqlite3_autovacuum_pages()接口的调用都会覆盖该连接先前的所有调用。如果sqlite3_autovacuum_pages()的回调参数(C)是一个NULL指针，则自动VACUUM页面步骤回调会被取消。sqlite3_autovacuum_pages()的返回值通常为SQLITE_OK，但如果出现错误，则可能是其他错误代码。当前的实现只返回SQLITE_OK或SQLITE_MISUSE，但其他返回代码可能会在未来的版本中添加。

如果未指定自动VACUUM页面回调（通常情况）或为回调提供了NULL指针，那么默认行为是清理所有免费页面。因此，换句话说，默认行为与如果回调函数类似。

如果该函数传入参数NULL函数指针，默认回调一个空行为，而回调函数的需要如下样子才是准确的：

unsigned int demonstration_autovac_pages_callback(
      void *pClientData,
      const char *zSchema,
      unsigned int nDbPage,
      unsigned int nFreePage,
      unsigned int nBytePerPage
    ){
      return nFreePage;
    }

4、sqlite3类的成员函数：sqlite3_db_filename函数

函数类型：

sqlite3_filename sqlite3_db_filename(sqlite3 *db, const char *zDbName);

获取连接到给定数据库文件的数据库实例的文件名。这个文件名可以是一个相对路径、绝对路径或者是一个特殊的“:memory:”字符串，代表一个临时数据库文件。

这个函数需要两个参数：一个sqlite3实例指针和一个整型参数。这个整型参数指定了数据库实例是第几个数据库连接，如果指定为0，函数会返回主数据库实例的文件名。如果指定的连接不合法，函数会返回空指针。

在使用sqlite3_db_filename()函数时，需要传入一个指向sqlite3数据库实例的指针。该函数会返回以NULL结尾的字符串，它是该数据库实例的文件路径名的副本。这个字符串可能是一个以null结尾的UTF-8编码的字符串，而且是只读的。如果指定的连接号不合法，那么该函数将会返回一个空指针。注意，如果已经打开了一个临时数据库，则该函数返回“:memory:”，而不是一个路径名。

sqlite3_db_filename()函数提供了一种非常方便的方法，可以确定指定数据库连接的文件名。它对于需要大量访问SQLite数据库的应用程序来说非常有用，可以从数据库实例路径中提取数据，并执行预期的操作。该函数可用于调试，错误处理和其他应用程序中的许多场景，可以帮助确定有问题的数据库文件的位置。

sqlite3_db_filename（D，N）接口返回指向文件名的指针与连接D的数据库N关联。如果数据库上没有附加的数据库N连接D，或者如果数据库N是临时数据库或内存中数据库，则此函数将返回NULL指针或空字符串。此例程返回的字符串值由数据库连接。该值将一直有效，直到数据库N是DETACH或直到数据库连接关闭。此函数返回的文件名是VFS的xFullPathname方法。换句话说，文件名将是绝对路径名，即使使用的文件名也是如此打开数据库最初是URI或相对路径名。

如果返回指针不是NULL，则返回值可以为以下函数提供参数：

sqlite3_uri_parameter()
sqlite3_uri_boolean()
sqlite3_uri_int64()
sqlite3_filename_database()
sqlite3_filename_journal()
sqlite3_filename_wal()

5.sqlite3类的成员函数：sqlite3_get_table函数

函数类型：

int sqlite3_get_table(
  sqlite3 *db,          /* An open database */
  const char *zSql,     /* SQL to be evaluated */
  char ***pazResult,    /* Results of the query */
  int *pnRow,           /* Number of result rows written here */
  int *pnColumn,        /* Number of result columns written here */
  char **pzErrmsg       /* Error msg written here */
);
void sqlite3_free_table(char **result);

 这是为向后兼容而保留的旧接口。不建议使用此接口。
定义：结果表是由sqlite3_get_table()接口创建的内存数据结构。结果表记录了完成一个或多个查询的查询结果。
从概念上讲，该表具有许多行和列。但这些数字不是结果表本身的一部分。这些数字是单独获得的。设N为行数M是列数。
结果表是指向以零结尾的UTF-8字符串的指针数组。数组中有（N+1）*M个元素。第一个M指针点转换为包含列名称的以零结尾的字符串。其余条目都指向查询结果。NULL值结果在NULL指针中。所有其他值都以UTF-8零结尾sqlite3_column_text()返回的字符串表示形式。
结果表可能由一个或多个内存分配组成。将结果表直接传递给sqlite3_free()是不安全的。应使用sqlite3_free_table()解除分配结果表。
作为结果表格式的示例，假设查询结果具体如下：
Name|Age
-----------------------
Alice   |43
Bob    |28
Cindy  |21
有两列（M==2）和三行（N==3）。因此，结果表有8个条目。假设结果表已存储在名为azResult的数组中。然后azResult保存以下内容：
azResult[0]="Name";
azResult[1]="Age";
azResult[2]="Alice";
azResult[3]="43";
azResult[4]="Bob";
azResult[5]="28";
azResult[6]="Cindy";
azResult[7]="21";
sqlite3_get_table()函数计算一个或多个以分号分隔的SQL语句，以零结尾的UTF-8string并返回结果表给在其第3个参数中给出的指针。
在应用程序完成sqlite3_get_table()的结果后，它必须将结果表指针传递给sqlite3_free_table()才能释放被错误分配的内存。由于sqlite3_malloc()在sqlite3_get_table()中发生的方式，调用函数不得尝试直接调用sqlite3_free()。只有sqlite3_free_table()能够正确安全地释放内存。
sqlite3_get_table()接口是作为sqlite3_exec()的包装器实现的。sqlite3_get_table()例程没有访问权限到SQLite的任何内部数据结构。它只使用公众此处定义的接口。因此，在内部sqlite3_exec()调用之外的包装层不是反映在对sqlite3_errcode()或sqlite3_errmsg()的后续调用中。

扩展:执行一个 SELECT 查询，并将结果存储在一个char**类型的二维数组中，该二维数组以NULL结尾。
函数执行SELECT查询语句并将结果存储在一个字符数组中，这个字符数组中包含了查询语句的所有结果，包括表头和每一行的数据。函数的使用必须通过sqlite3_free()函数来释放该函数返回指针指向的内存空间。
sqlite3_get_table()函数需要传递6个参数，它们分别是：数据库连接、需要执行的SQL语句、指向二维字符数组的指针、行数（包含表头）、列数（包含列名）和错误信息（两者都是输出参数）。其中，前三个参数是必须的，后三个参数是可选的。
sqlite3_get_table()函数可以方便地将执行结果返回到字符数组中，而无需使用sqlite3_step()循环来逐行获取结果。由于这个函数能够减少SQL查询的复杂性，因此对于需要执行简单SELECT查询的应用程序来说是非常有用的。但是当数据库中的数据量很大时，使用sqlite3_get_table()可能会导致内存泄漏和响应时间变慢。

参考文献：

1. C-language Interface Specification for SQLite官方说明文档