首页 › sqlite › sqlite之我见–C/C++ API接口介绍

sqlite之我见–C/C++ API接口介绍

第七根弦 2016 年 12 月 21 日 sqlite 发表评论 (0)

上一篇文章sqlite之我见–简单介绍与基本操作已经初步介绍了sqlite一些基本的知识与简单的操作，这里我们接着介绍最重要的部分，如何将sqlite用到我们的程序中。
1. 概论
sqlite3是为了满足以下需求而开发的
1）支持UTF-16编码
2）用户自定义的文本排序方法
3）可以对BLOBs字段建立索引

NOTE:sqlite3跟之前的版本数据库格式是不兼容的

最简单的程序可以用sqlite3_open(), sqlite3_exec(), sqlite3_close()3个接口来完成。
如果想更好地控制数据库引擎，可以用sqlite3_prepare()来把SQL语句编译成字节码，然后使用sqlite3_step()来执行编译后的字节码。以sqlite3_column_开头的一组API来获取查询结果集中的信息。

接下来我们先介绍一下SQLITE的一些常用API函数：

typedef struct sqlite3 sqlite3; //数据库连接对象
typedef struct sqlite3_stmt sqlite3_stmt; //预处理语句对象


2. API接口介绍
1）sqlite3_open_v2

C++
1
2
3
4
5
6
int sqlite3_open_v2(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb,            /* OUT: SQLite db handle */
  int flags,                        /* Flags */
  const char *zVfs           /* Name of VFS module to use */
);

该接口打开与一个sqlite数据库文件的连接并返回一个数据库连接对象，相当于文件句柄。这通常是应用程序调用的第一个SQLITE API接口，而且也是调用其他SQLite API接口前需要调用的接口。许多SQLite接口需要一个指向数据库连接对象的指针作为它们的第一个参数，因而这些接口也可以理解成数据库连接对象的操作接口。该接口就是创建了这样一个数据库连接对象。
Note：打开/创建数据库的命令会被缓存，直到这个数据库被真正地调用的时候才会被执行。而且允许使用PRAGMA声明来设置如本地文本编码或者默认内存页面大小等选项和参数。

C++
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
#define SQLITE_OK                       0   /* Successful result */
#define SQLITE_ERROR          1   /* SQL error or missing database */
#define SQLITE_INTERNAL       2   /* An 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 sqlite_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   /* (Internal Only) Table or record not found */
#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   /* (Internal Only) Database table is empty */
#define SQLITE_SCHEMA         17   /* The database schema changed */
#define SQLITE_TOOBIG         18   /* Too much data for one row of a table */
#define SQLITE_CONSTRAINT     19   /* Abort due to contraint 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_ROW            100  /* sqlite_step() has another row ready */
#define SQLITE_DONE           101  /* sqlite_step() has finished executing */

2）sqlite3_exec

C++
1
2
3
4
5
6
7
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 */
);

此接口是一个对sqlite3_prepare_v2, sqlite3_step, sqlite3_finalize接口的便捷封装，以便应用程序可以用少量的代码来运行多条SQL语句。
参数解释：第1个为数据库连接对象，通过sqlite3_open得到；第2个为要实行的SQL语句，使用UTF-8编码，多条语句使用分号间隔；第3个为回调函数，对结果进行处理，第4个为传递给callback函数的第一个参数；第5个参数，当该接口执行错误的时候，可以得到错误信息。
Note:如果sqlite3_exec执行错误，errmsg有错误返回的时候，在调用sqlite3_close()之前，必须调用sqlite3_free来释放掉sqlite3_malloc()的内存。

3）sqlite3_prepare_v2

1
2
3
4
5
6
7
int sqlite3_prepare_v2(
  sqlite3 *db,                /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,               /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,   /* OUT: Statement handle */
  const char **pzTail      /* OUT: Pointer to unused portion of zSql */
);

该接口把一个SQL语句文本转换成一个预处理语句对象并返回一个指向该对象的指针。这个接口需要之前由sqlite3_open_v2()返回的数据库连接对象指针以及一个预处理的SQL语句文本字符串作为参数。这个API并不实际解析SQL语句，仅仅是为后续的解析而对SQL语句进行的预处理。
该函数处理的sql语句必须是UTF-8编码的，输入的参数（第2个）中，只有第一个sql语句会被编译，而第5个参数则用来指向输入参数中下一个需要编译的sql语句存放的sqlite statement对象的指针。
在SQL语句文本中，跟下列各式匹配的字面值可以通过下面的sqlite3_bind_*接口进行绑定。

  • ?
  • ?NNN
  • :VVV
  • @VVV
  • $VVV

4）sqlite3_bind_

C++
1
2
3
4
5
6
7
8
9
int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
int sqlite3_bind_double(sqlite3_stmt*, int, double);
int sqlite3_bind_int(sqlite3_stmt*, int, int);
int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
int sqlite3_bind_null(sqlite3_stmt*, int);
int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);

以上sqlite3_bind 接口族，用来给SQL声明中的通配符赋值的.没有绑定的通配符则被认为是空值.绑定上的值不会被sqlite3_reset()函数重置.但是在调用了sqlite3_reset()之后所有的通配符都可以被重新赋值.
该接口族的第2个参数是被设定通配符的index值，从1开始。

5）sqlite3_step

C++
1
int sqlite3_step(sqlite3_stmt*);

该接口用于解析一个由先前通过sqlite3_prepare_v2()接口创建的预处理语句对象，直至返回第一行结果为止。通过再次调用sqlite3_step()可以返回下一行的结果，继续不断地调用sqlite3_step()直至整个语句完成为止。对于那些不返回结果的语句（例如INSERT,DELETE,UPDATE语句）一次调用sqlite3_step()就完成了语句的处理。
返回值：如果sql语句执行成功则返回SQLITE_DONE，
如果sql返回了一个单行结果集，函数返回SQLITE_ROW，这种情况要调用sqlite3_column_*函数来获得记录集行中的数据。
出错，返回错误码，例如SQLITE_BUSY

6）sqlite3_column 接口族
sqlite3_column()接口族，该接口返回一个由sqlite3_step()解析的预处理语句结果集中当前行的某一列数据。每次执行sqlite3_step()都返回一个新的结果集中的一行。可以多次调用sqlite3_column()接口返回那一行中所有列的数据。SQLite API中并没有sqlite3_column()这样的接口，取而代之的是一组用于从结果集中查询出各个列项各种数据类型数据的函数接口。在这组函数中，有些返回结果集的大小，有些返回结果集的列数。

C++
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
const void *        sqlite3_column_blob(sqlite3_stmt*, int iCol);
int                            sqlite3_column_bytes(sqlite3_stmt*, int iCol);
int                  sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
double                sqlite3_column_double(sqlite3_stmt*, int iCol);
int                    sqlite3_column_int(sqlite3_stmt*, int iCol);
sqlite3_int64          sqlite3_column_int64(sqlite3_stmt*, int iCol);
const unsigned char*  sqlite3_column_text(sqlite3_stmt*, int iCol);
const void *          sqlite3_column_text16(sqlite3_stmt*, int iCol);
int                    sqlite3_column_type(sqlite3_stmt*, int iCol);
sqlite3_value *        sqlite3_column_value(sqlite3_stmt*, int iCol);
int                 sqlite3_column_count(sqlite3_stmt *pStmt);
 
int sqlite3_column_count(sqlite3_stmt *pStmt);
//该接口返回结果集中包含的列数，该接口可在执行了sqlite3_prepare_v2()之后的任何时刻调用。如果sqlite3_step()执行的是一个没有返回数据的语句，那么该接口会返回0.
 
int sqlite3_data_count(sqlite3_stmt *pStmt);
//该接口必须在sqlite3_step()之后调用，其他跟sqlite3_column_count()基本相同。

NOTE：如果sqlite3_step()返回SQLITE_DONE或者错误代码，则sqlite3_data_count会返回0，而sqlite3_column_count仍然会返回结果集包含的列数。

返回的结果集通过其他的几个sqlite3_column_***()函数来提取，所有的这些函数都把列的编号作为第2个参数，列编号从左到右，从0开始。

C++
1
2
3
4
5
6
7
int sqlite3_column_type(sqlite3_stmt*, int iCol);
//该接口返回第iCol列的值的数据类型。具体返回值如下：
#define SQLITE_INTEGER   1
#define SQLITE_FLOAT     2
#define SQLITE_TEXT      3
#define SQLITE_BLOB      4
#define SQLITE_NULL      5

NOTE：不一定非要按照该接口返回的数据类型来获取数据。数据类型不同时软件会自动转换。

7）sqlite3_reset
int sqlite3_reset(sqlite3_stmt*);
该接口用来重置一个SQL预处理语句对象的状态，使得它可以被再次执行。

8）sqlite3_finalize
int sqlite3_finalize(sqlite3_stmt*);
该接口销毁之前调用sqlite3_prepare_v2()创建的预处理语句对象。每一预处理语句对象都必须调用这个接口进行销毁以避免内存泄露大笑。
任何时候调用该接口，都会销毁一个prepared的sql声明，在sqlite3_close()之前，必须通过该接口将所有prepared的声明释放销毁。

9）sqlite3_close
int sqlite3_close(sqlite3 *);
该接口销毁之前调用sqlite3_open_v2()创建的数据库连接对象。所有与该连接相关的预处理语句对象都必须在关闭连接之前销毁，否则该接口会返回让你头疼的SQLITE_BUSY。
下一篇文章 sqlite之我见–C/C++ API接口示例 中，我会用一些小程序来示例SQLite C/C++ API的使用。

|

发表评论