SQLite数据库核心API

SQLite核心API是用于执行基本数据库操作的函数，包括：连接数据库、处理SQL、迭代查询结果。还有有助于字符串格式化、运行控制、调试和错误处理的实用函数。我们可以将sqlite3结构指针看做是一个对象，sqlite_open()等连接函数看做是它的构造函数，sqlite_close()等断开函数看做是它的析构函数，其他一些函数是它的成员方法。

 

1 连接与断开连接

在执行SQL命令前，首先要打开数据库文件（SQLite数据库包含在单个操作系统文件中）。可以用sqlite_open()、sqlite_open_v2()或sqlite_open16()函数打开数据库。声明如下：

int sqlite3_open(const void *filename, sqlite3 **ppDb); 

int sqlite3_open_v2(const void*filename, sqlite2 **ppDb, int flags, const char *zVfs);

int sqlite3_open16(const void *filename, sqlite3 **ppDb);

下面主要介绍sqlite3_opern()函数，虽然它没有sqlite3_open_v2()那么强大，但是仍然是一个非常好用的一个打开数据库的函数。

1.1 作用

使用参数filename打开一个数据库文件，如果名为filename的数据库文件不存在，那么则新建一个数据库文件；将该数据库文件的句柄和ppDb绑定起来并用指针返回，使得其他数据库操作函数可以使用。例如，

#include <sqlite3.h>

static sqlite3 *pMediaNoteDb = NULL;    //数据库文件句柄
const char sqliteFilePath[] = "/media/sda/sqliteMediaNote.db";    //数据库文件存放路径+数据库文件名

int ret = sqlite3_open(sqliteFilePath, &pMediaNoteDb);    //打开数据库

1.2 参数

（1）const char *filename，filename可以是单独数据文件名也可以是带有完整路径的数据库文件名。

· 数据库文件名"sqliteMediaNote.db"，如果数据库文件名参数只是数据库文件名，那么，sqlite3_open()函数会在当前代码存放目录下打开或创建数据库文件。其实数据库文件一般不与执行程序文件存放在同一目录下，所以可以filename参数可以使用下面带完整路径的字符串形式。

· 绝对路径"/media/sda/sqliteMediaNote.db"，打开文件夹/media/sda下的数据库文件"sqliteMediaNote.db"；注意这个文件路径必须存在并且必须是绝对路径，否则会报错unable to open database file。

（2）sqlite3 **ppDB，这是一个指向数据库文件句柄类型的二重指针，通常我们在新建一个SQL数据库时会定义一个数据库句柄类型指针并初始化。

1.3 返回值

如果数据库文件打开成功，返回0；失败则返回正整数。SQLite数据库中为我们定义了一系列宏，可以通过sqlite3_errmsg()函数打印调试信息。

/* Successful result */
#define SQLITE_OK           0   

/* beginning-of-error-codes */
#define SQLITE_ERROR        1   /* SQL error or missing database */
#define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
#define SQLITE_PERM         3   /* Access permission denied */
#define SQLITE_ABORT        4   /* Callback routine requested an abort */
#define SQLITE_BUSY         5   /* The database file is locked */
#define SQLITE_LOCKED       6   /* A table in the database is locked */
#define SQLITE_NOMEM        7   /* A malloc() failed */
#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
#define SQLITE_NOTFOUND    12   /* Unknown opcode in sqlite3_file_control() */
#define SQLITE_FULL        13   /* Insertion failed because database is full */
#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
#define SQLITE_EMPTY       16   /* Database is empty */
#define SQLITE_SCHEMA      17   /* The database schema changed */
#define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
#define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
#define SQLITE_MISMATCH    20   /* Data type mismatch */
#define SQLITE_MISUSE      21   /* Library used incorrectly */
#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
#define SQLITE_AUTH        23   /* Authorization denied */
#define SQLITE_FORMAT      24   /* Auxiliary database format error */
#define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
#define SQLITE_NOTADB      26   /* File opened that is not a database file */
#define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
#define SQLITE_DONE        101  /* sqlite3_step() has finished executing */

打开数据库文件完成后，sqlite3_open()将初始化ppDb指向的sqlite3结构体，该结构体代表着到数据库的一个连接。

使用sqlite3_close()函数可以关闭当前与数据库文件的连接，声明如下：

int sqlite3_close(sqlite3 *pDb);

其返回值与sqlite3_open()函数一样，参数sqlite3 *是数据库文件句柄。要成功执行sqlite3_close()，必须完成与连接关联的所有准备查询。只要有一个查询任未完成，sqlite_close()都会返回SQLITE_BUSY，但是sqlite_close()会自动回滚，当所有查询完成时关闭连接会完成。

 

2 处理SQL

2.1 执行查询-函数sqlite_exec()

sqlite_exec()函数提供一种快速、方便执行SQL命令的方法， 对修改数据库的命令（即不放回任何数据的命令）特别方便。声明如下：

int sqlite3_exec(sqlite *pDb, const char *sql, sqlite_callback, void *data, char **errmsg);

2.1.1 作用：执行SQL命令

2.1.2 参数

（1）sqlite *pDb，数据库文件句柄。该句柄必须是已与数据库文件连接。

（2）const char *sql，sql字符串中包含一个或多个SQL命令，每条命令用分号";"隔开。sqlite3_exec()将逐一解析和执行sql字符串中的每个命令，直到达到字符串末尾或者遇到错误，如果中间某条SQL命令执行出错，那么接下来的语句将被跳过不执行。还需要注意一个问题SQL命令一般都比较长，在一行的范围内很难写下而且也很不美观，我们可能会想到换行符"\"，但是它不利于我们使代码看起来简洁美观，因为采用缩进的方式的话，开头的空格也会算入字符串中。如下：

char *creatMediaNOteSqliteTable = "CREAT TABLE media(\
idx integer primary key autoincrement,\
chn int,\
recType int,\
startTime long,\
endTime long,\
pos int,\
path vchar,\
name vchar,\
alarmsrc vchar,\          
playTime long)";
 

我们可以使用连续的""包起来的字符串，它会默认合并为一个字符串常量，例如：

char *creatMediaNOteSqliteTable = "CREAT TABLE media("
　　　　　　　　　　　　　　　　　　　　 "idx integer primary key autoincrement,"
　　　　　　　　　　　　　　　　　　　　 "chn int,"
　　　　　　　　　　　　　　　　　　　　 "recType int,"
　　　　　　　　　　　　　　　　　　　　 "startTime long,"
　　　　　　　　　　　　　　　　　　　　 "endTime long,"
　　　　　　　　　　　　　　　　　　　　 "pos int,"
　　　　　　　　　　　　　　　　　　　　 "path vchar,"
　　　　　　　　　　　　　　　　　　　　 "name vchar,"
　　　　　　　　　　　　　　　　　　　　 "alarmsrc vchar,"          
　　　　　　　　　　　　　　　　　　　　 "playTime long)";

 （3）int (*callback)(void *, int, char **, char **)（4）void *data是sqlite3_exec()函数提供的回调机制用于获取记录。但是我们使用sqlite3_exec()函数就是为了快速方便，获取记录可以使用其他的查询函数。

 （4）char **errmsg，*errmsg是指向错误消息字符串的指针，sqlite3_exec()会将发生的错误消息写到该字符串中。如果*errmsg不为NULL，那么错误消息将会存储在*errmsg指向的内存中。这段内存是通过sqlite3_malloc()申请的堆空间，为了避免内存泄漏，我们打印完当前的错误消息后，要用sqlite3_free()释放这段内存。

2.1.3 返回值：sqlite3_exec()函数的返回值与sqlite3_open()函数一样，"0"表示函数执行成功。

下面是sqlite3_exec()函数的一个实例：

//数据库创建SQL
staic char *pCreatMediaNOteSqliteTable = "CREAT TABLE media("
　　　　　　　　　　　　　　　　　　　　 "idx integer primary key autoincrement,"
　　　　　　　　　　　　　　　　　　　　 "chn int,"
　　　　　　　　　　　　　　　　　　　　 "recType int,"
　　　　　　　　　　　　　　　　　　　　 "startTime long,"
　　　　　　　　　　　　　　　　　　　　 "endTime long,"
　　　　　　　　　　　　　　　　　　　　 "pos int,"
　　　　　　　　　　　　　　　　　　　　 "path vchar,"
　　　　　　　　　　　　　　　　　　　　 "name vchar,"
　　　　　　　　　　　　　　　　　　　　 "alarmsrc vchar,"          
　　　　　　　　　　　　　　　　　　　　 "playTime long)";

char *errMsg = NULL;
int ret = sqlite3_exec(pMediaNoteDb, pCreatMediaNoteSqliteTable, NULL, NULL, &errMsg);    //执行数据库创建SQL命令
if (ret){
    if (strcmp("table media already exists", errMsg) != 0){
        printf("Creat media table err: ret = %d, %s\n", ret, errMsg);
        return -1;
    }
}
sqlite3_free(errMsg);    //释放errMsg指向的堆空间
printf("Open DataBase success\n");

return 0;

2.2 获取表查询-函数sqlite3_get_table()

 声明如下：

int sqlite3_get_table(sqlite3 *pDb, const char *sql, char ***pResult, int *nrow, int *ncolumn, char **errmsg);

2.2.1 作用：返回执行命令后的整个结果集，用于执行返回数据的查询。但要注意的是：sqlite3_get_table()将结果集完全存储在内存中，这样结果集越大，占用的内存就越多，因此，使用它来检索大的结果集并不合适。

sqlite3_get_table()封装了sqlite3_exec()并便捷的返回数据，使用sqlite3_get_table()，不必操心sqlite3_exec()回调函数，从而获取记录更容易。

2.2.2 参数

（1）char ***pResult，pResult存放着指针数组的地址。指针数组有(row + 1) * column个元素，开始的column个元素分别指向结果集中列的名称，剩余的元素都指向查询结果。结果集如下所示：

pResult指向的内存空间由sqlite3_malloc()函数在堆上申请得到，使用完后用sqlite3_free_table()释放内存。

（2）int *nrow，结果集中行数row+1。

（2）int *ncolumn,结果集中列数column。

2.2.3 返回值：sqlite3_get_table()函数的返回值与sqlite3_open()函数相同。

 

3 调试、错误处理

3.1 const char *sqlite3_errmsg(sqlite3 *pDb);

3.1.1 作用：输出链接数据库时的错误信息。

3.1.2 参数sqlite *pDb，数据库句柄指针。

3.1.3 返回值：指向错误信息字符串指针。不过不用担心错误信息所占内存，因为接下来的接口函数到来时，会自动重写或者释放这段内存。

 

该篇博客是自己的学习博客，水平有限，如果有哪里理解不对的地方，希望大家可以指正！

转载于:https://www.cnblogs.com/zpchya/p/11177920.html