Convenience Routines For Running Queries

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 指针。所有其他值都是以 sqlite3_column_text() 返回的 UTF-8 零终止字符串表示形式表示的。

结果表可能包含一个或多个内存分配。将结果表直接传递给 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() 函数计算第二个参数的零终止 UTF-8 字符串中的一个或多个以分号分隔的 SQL 语句，并将结果表返回给第三个参数中指定的指针。

在应用程序完成 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() 时反映出来。