SQlite数据库的C编程接口（五） 便捷函数（Convenience Functions） ——《Using SQlite》读书笔记

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

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

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

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

  总之，作者Jay A. Kreibich非常不推荐使用这些便捷函数。正如他说的：“If you’re just trying to throw together a quick and dirty snippet of code,these functions provide an easy means of doing that.I strongly recommend using the normal prepare, step, and finalize routines. You’ll end up with safer code and better performance.”

  (1)

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函数来释放。

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