sqlite3 C/C++ 开发接口简介（API函数） 一
作者：林轩 来源：www.sqlite.com.cn
1.0 总览
sqlite3是sqlite一个全新的版本,它虽然是在sqlite 2.8.13的代码基础之上开发的,但是使用了和之前的版本不兼容的数据库格式和API. sqlite3是为了满足以下的需求而开发的:
支持UTF-16编码.
用户自定义的文本排序方法.
可以对BLOBs字段建立索引.
因此为了支持这些特性我改变了数据库的格式,建立了一个与之前版本不兼容的3.0版. 至于其他的兼容性的改变,例如全新的API等等,都将在理论介绍之后向你说明,这样可以使你最快的一次性摆脱兼容性问题.
3.0版的和2.X版的API非常相似,但是有一些重要的改变需要注意. 所有API接口函数和数据结构的前缀都由"sqlite_"改为了"sqlite3_". 这是为了避免同时使用sqlite 2.X和sqlite 3.0这两个版本的时候发生链接冲突.
由于对于C语言应该用什么数据类型来存放UTF-16编码的字符串并没有一致的规范. 因此sqlite使用了普通的void* 类型来指向UTF-16编码的字符串. 客户端使用过程中可以把void*映射成适合他们的系统的任何数据类型.
2.0 C/C++ 接口
sqlite 3.0一共有83个API函数,此外还有一些数据结构和预定义(#defines). (完整的API介绍请参看另一份文档.) 不过你们可以放心,这些接口使用起来不会像它的数量所暗示的那么复杂. 最简单的程序仍然使用三个函数就可以完成: sqlite3_open(),sqlite3_exec(),和 sqlite3_close(). 要是想更好的控制数据库引擎的执行,可以使用提供的sqlite3_prepare()函数把sql语句编译成字节码,然后在使用sqlite3_step()函数来执行编译后的字节码. 以sqlite3_column_开头的一组API函数用来获取查询结果集中的信息. 许多接口函数都是成对出现的,同时有UTF-8和UTF-16两个版本. 并且提供了一组函数用来执行用户自定义的sql函数和文本排序函数.
2.1 如何打开关闭数据库
typedef struct sqlite3 sqlite3;
int sqlite3_open(const char*,sqlite3**);
int sqlite3_open16(const void*,sqlite3**);
int sqlite3_close(sqlite3*);
const char *sqlite3_errmsg(sqlite3*);
const void *sqlite3_errmsg16(sqlite3*);
int sqlite3_errcode(sqlite3*);
sqlite3_open() 函数返回一个整数错误代码,而不是像第二版中一样返回一个指向sqlite3结构体的指针. sqlite3_open() 和 sqlite3_open16() 的不同之处在于sqlite3_open16() 使用UTF-16编码(使用本地主机字节顺序)传递数据库文件名. 如果要创建新数据库,sqlite3_open16() 将内部文本转换为UTF-16编码,反之sqlite3_open() 将文本转换为UTF-8编码.
打开或者创建数据库的命令会被缓存,直到这个数据库真正被调用的时候才会被执行. 而且允许使用PRAGMA声明来设置如本地文本编码或默认内存页面大小等选项和参数.
sqlite3_errcode() 通常用来获取最近调用的API接口返回的错误代码. sqlite3_errmsg() 则用来得到这些错误代码所对应的文字说明. 这些错误信息将以 UTF-8 的编码返回,并且在下一次调用任何sqlite API函数的时候被清除. sqlite3_errmsg16() 和 sqlite3_errmsg() 大体上相同,除了返回的错误信息将以 UTF-16 本机字节顺序编码.
sqlite3的错误代码相比sqlite2没有任何的改变,它们分别是:
#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 */
