sqlite数据库的C编程接口（五） 便捷函数（Convenience Functions） by斜风细雨QQ：253786989 2012-02-07

sqlite拥有很多早期遗留下来的便捷函数，这些函数存在很多缺点。当然他们依然存在就有理由——使用方便。

它们的优点也仅仅是使用方便，而不是具有很好的性能。相反，它们的性能会比直接调用PUBLICAPI函数更差一些。对于这些便捷函数，它们并没有什么特别之处，只是在这些函数内部调用sqlite3_prepare_xxx、sqlite3_step、sqlite3_finalize等API函数来完成一站式功能。在这样的函数内部往往存在很多额外的类型转换，所以这些函数很可能会比我们自己去调用sqlite3_prepare_xxx、sqlite3_step、sqlite3_finalize等API执行的更慢一些。

其次，这些API不支持参数绑定。就像上一篇笔记中介绍的，这样的程序更容易遭到“sql注入攻击”，安全性更差。

总之，作者JayA.Kreibich非常不推荐使用这些便捷函数。正如他说的：“Ifyou’rejusttryingtothrowtogetheraquickanddirtysnippetofcode,thesefunctionsprovideaneasymeansofdoingthat.Istronglyrecommendusingthenormalprepare,step,andfinalizeroutines.You’llendupwithsafercodeandbetterperformance.”

(1)

@H_404_69@int sqlite3_exec( sqlite3*,/* An open database */ const char *sql,/* sql to be evaluated */ int (*callback)(void*,int,char**,char**),/* Callback function */ void *,/* 1st argument to callback */ char **errmsg /* Error msg written here */ );

预处理（prepare）和执行（execute）一条或多条sql语句，对结果集的每一行调用其第3个参数所指向的回调函数。第1个参数指向一个有效的数据库连接。第2个参数是UTF-8编码的sql语句（可以包含一条，或多条：以分号隔开）。第3个参数是一个指向回调函数的指针，如果不需要使用回调函数，可以给该参数传递NULL。第4个参数也是一个指针，用来传递用户数据到回调函数。需要注意的是，比如该指针由sqlite3_malloc获得，则要在其不再使用时调用sqlite3_free函数释放。第5个参数是一个指向指针的指针，通过该参数返回错误码。如果在sqlite3_exec执行过程中，没有遇到任何错误，最后函数将返回sqlITE_OK。

比如sqlite3_exec正在执行SELECT查询操作，而且想对返回结果进行处理。那就要传递一个回调函数给sqlite3_exec。这样sqlite3_exec函数每次获取一行数据，就会调用该回调函数。如果sqlite3_exec正在执行的操作不返回数据，就直接给sqlite3_exec函数的第3个参数传递NULL就可以了。

回调函数原型：

int user_defined_exec_callback( void *userData,int numCol,char **colData,char **colName )

第1个参数对应于sqlite3_exec函数的第4个参数，用于传递用户数据。第2个参数指明结果集中一共有多少列。第3个参数保存当前数据行的数据，第4个参数保存当前数据行的所有列的列名。第3个参数和第4个参数都是以字符串的形式返回。

正常情况下，回调函数应该返回0，如果它返回一个非0值，则sqlite3_exec函数将终止执行，并返回sqlITE_ABORT错误码。

(2)

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 */
);

这个函数与sqlite3_exec函数不同，它只在sql命令字符串执行完成之后，返回全部的结果数据。该函数是专门针对SELECT语句设计的。

第1个参数是指向数据库连接的指针。第2个参数是UTF-8编码的sql命令字符串。第3个参数看起来有点复杂，通过该参数返回sql语句执行结果。首先该参数是一个指针，它指向一个一维数组，这个一维数组里面保存的元素类型是字符串指针。第4个和第5个参数返回结果集中的行数和列数。最后一个参数返回错误码。

函数执行完成返回的结果集中，包含（nColumn*(nRow+1)）个数据项。其中多出来的一行是列名，剩下的nColumn*nRom项是数据。

如果sqlite3_get_table函数执行过程中没遇到任何错误，最后会返回sqlITE_OK。

下面是对结果集的一个访问例子，获取结果集中第R行，第C列的数据：

/* offset to access column C of row R of **result */
int  offset  = ((R + 1) * numCol) + C;
char *value  = result[offset];

传递给sqlite3_get_table函数的sql命令字符串可以包含多条SELECT语句。但是，对于这多条SELECT语句的返回结果全部存储在pazResult所指向的一维数组中。没有办法确定一维数组中，哪些行数据是哪个SELECT语句检索出来的。并且所有的SELECT语句所返回的列数必须相同，否则sqlite3_get_table函数执行失败。除此之外，只有第一条语句会返回列名，存储在结果集一维数组的第一行中。基于以上原因，最好在每次调用sqlite3_get_table函数时使用单独一条sql命令。

（3）

void sqlite3_free_table(char **result);

由sqlite3_get_table函数返回的结果集，所占用的内存，需要由sqlite3_free_table函数来释放。