小。速度很快。可靠。
选择任意三个选项。

注：本文档是在2004年编写的，作为帮助程序员的指南从使用SQLite版本2转移到使用SQLite版本3。信息在本文中基本上仍然是正确的，但是多年来进行了许多更改和增强。我们建议应使用以下文件：

SQLite版本3的C/C++接口

1.0概述

SQLite 3.0版是SQLite的新版本，源自SQLite 2.8.13代码库，但文件格式不兼容和API。创建SQLite 3.0版是为了满足以下功能的需求：

为了实现这些功能，有必要迁移到3.0版，因为每个都需要对数据库文件格式进行不兼容的更改。其他在同时根据理论，最好是得到不相容的更改立刻让开。

3.0版的API与2.X版的API类似，但有一些重要的变化。最引人注目的是，“方石英_"出现在所有API函数和数据开头的前缀结构更改为“方形3_". 这避免了两个API之间的混淆，并允许针对这两个API进行链接同时使用SQLite 2.X和SQLite 3.0。

UTF-16的C数据类型没有达成一致字符串应该是。因此，SQLite使用了一种通用类型的void*以参考UTF-16字符串。客户端软件可以填补空白*到适合其系统的任何数据类型。

2.0 C/C++接口

SQLite 3.0的API还包括83个单独的函数到几个数据结构和#定义。（A完整API参考作为单独的文档。）幸运的是，接口并不像其大小所暗示的那样复杂。简单的程序仍然只能使用3种功能：sqlite3_open（）,sqlite3_exec（）、和sqlite3_close（）.提供了对数据库引擎执行的更多控制使用sqlite3_prepare_v2（）将SQLite语句编译为字节码sqlite3_step（）来执行字节码。名称以开头的一系列例程sqlite3_列_用于提取有关查询结果集的信息。许多接口函数成对出现，其中包括UTF-8和UTF-16版本。这里有一组例程用于实现用户定义的SQL函数和用户定义的文本排序序列。

2.1打开和关闭数据库

typedef结构sqlite3 sqlite3；int sqlite3_open（常量字符*，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（）例程返回整数错误代码，而不是像版本2接口那样指向sqlite3结构的指针。sqlite3_open（）之间的差异而sqlite3_open16（）是sqlite3_apen16（）接受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。

SQLite版本3的错误代码与版本2相同。具体如下：

#定义SQLITE_OK 0/*成功结果*/#定义SQLITE_ERROR 1/*SQL错误或缺少数据库*/#define SQLITE_INTERNAL 2/*SQLITE中的内部逻辑错误*/#define SQLITE_PERM 3/*拒绝访问权限*/#define SQLITE_ABORT 4/*回调例程请求中止*/#define SQLITE_BUSY 5/*数据库文件被锁定*/#define SQLITE_LOCKED 6/*数据库中的表被锁定*/#define SQLITE_NOMEM 7/*malloc（）失败*/#define SQLITE_READONLY 8/*尝试写入只读数据库*/#define SQLITE_INTERRUPT 9/*操作被SQLITE_INTERRUPT（）终止*/#define SQLITE_IOERR 10/*发生了某种磁盘I/O错误*/#define SQLITE_CORRUPT 11/*数据库磁盘映像格式错误*/#define SQLITE_NOTFOUND 12/*（仅限内部）找不到表或记录*/#define SQLITE_FULL 13/*由于数据库已满，插入失败*/#define SQLITE_CANTOPEN 14/*无法打开数据库文件*/#define SQLITE_PROTOCOL 15/*数据库锁定协议错误*/#define SQLITE_EMPTY 16/*（仅限内部）数据库表为空*/#define SQLITE_SCHEMA 17/*数据库模式已更改*/#define SQLITE_TOOBIG 18/*表的一行数据太多*/#define SQLITE_CONSTRAINT 19/*由于违反约束而中止*/#define SQLITE_MISMATCH 20/*数据类型不匹配*/#定义SQLITE_MISUSE 21/*库使用不正确*/#define SQLITE_NOLFS 22/*使用主机上不支持的操作系统功能*/#define SQLITE_AUTH 23/*授权被拒绝*/#define SQLITE_ROW 100/*SQLITE_step（）有另一行就绪*/#define SQLITE_DONE 101/*SQLITE_step（）已完成执行*/

2.2执行SQL语句

typedef int（*sqlite_callback）（void*，int，char**，char**）；int sqlite3_exec（sqlite3*，const char*sql，sqlite_callback，void*，char**）；

这个sqlite3_exec（）该函数的工作方式与SQLite版本2中的类似。编译第二个参数中指定的零个或多个SQL语句并执行。查询结果将返回到回调例程。

在SQLite版本3中，sqlite3_exec例程只是围绕调用准备好的语句接口。

typedef结构sqlite3_stmt sqlite3_stmt；int sqlite3_prepare（sqlite3*，常量字符*，int，sqlite3_stmt**，常量字符**）；int sqlite3_prepare16（sqlite3*，const void*，int，sqlite3_stmt**，const void**）；int sqlite3_finalize（sqlite3_stmt*）；int sqlite3_reset（sqlite3_stmt*）；

sqlite3_prepare接口将单个SQL语句编译为字节码以便以后执行。此接口现在是访问的首选方式数据库。

SQL语句是sqlite3_prepare（）的UTF-8字符串。sqlite3_prepare16（）的工作方式相同，但它需要UTF-16字符串作为SQL输入。只编译输入字符串中的第一条SQL语句。第五个参数用指向下一个（未编译）的指针填充输入字符串中的SQLite语句（如果有）。sqlite3_finalize（）例程释放准备好的SQL语句。必须完成所有准备好的报表，然后才能建立数据库关闭。sqlite3_reset（）例程重置准备好的SQL语句，以便可以再次执行。

SQL语句可能包含“？”或“？nnn”或“：aaa”形式的标记其中“nnn”是整数，“aaa”是标识符。此类标记表示未指定的文字值（或“通配符”）稍后由sqlite3_绑定接口。每个通配符都有一个关联的数字，该数字是其在语句或“nnn”（如果是“？nnn”形式）。允许使用相同的通配符在同一SQL语句中出现多次，在这种情况下该通配符的所有实例都将使用相同的值填充。未绑定通配符的值为NULL。

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，long long int）；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 n，void（*）（void*））；int sqlite3_bind_value（sqlite3_stmt*，int，const sqlite3_ value*）；

有多种sqlite3_bind例程用于赋值到准备好的SQL语句中的通配符。未绑定通配符被解释为NULL。sqlite3_reset（）不会重置绑定。但通配符可以在sqlite3_reset（）之后反弹为新值。

在准备好SQL语句（并且可以选择绑定）之后使用以下命令执行：

int sqlite3_step（sqlite3_stmt*）；

如果sqlite3_step（）例程返回单个结果集的行，或SQLITE_DONE（如果执行已完成）正常或由于错误。如果是，它还可能返回SQLITE_BUSY无法打开数据库文件。如果返回值为SQLITE_ROW，则以下例程可用于提取有关该行的信息结果集的：

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）；int sqlite3_column_count（sqlite3_stmt*）；const char*sqlite3_column_decltype（sqlite3_stmt*，int iCol）；const void*sqlite3_column_decltype16（sqlite3_stmt*，int iCol）；双sqlite3_column_double（sqlite3_stmt*，int iCol）；int sqlite3_column_int（sqlite3_stmt*，int iCol）；long long int sqlite3_column_int64（sqlite3_stmt*，int iCol）；const char*sqlite3_column_name（sqlite3_stmt*，int iCol）；const void*sqlite3_column_name16（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_column_count（）函数返回中的列数结果集。sqlite3_column_count（）可以在sqlite3_prepare_v2（）.sqlite3_data_count（）工作原理类似于sqlite3_column_count（）除了它只在以下情况下工作sqlite3_step（）.如果上次呼叫sqlite3_step（）返回SQLITE_DONE或错误代码，然后sqlite3_data_count（）将返回0，而sqlite3_column_count（）将继续返回结果集中的列数。

使用另一个检查返回的数据sqlite3_列***（）功能，所有这些都以列号作为第二个参数。列是从左到右为零。注意，这与参数不同，从1开始索引。

这个sqlite3_column_type（）函数返回第N列中的值的数据类型。返回值为1其中：

#定义SQLITE_INTEGER 1#定义SQLITE_FLOAT 2#定义SQLITE_TEXT 3#定义SQLITE_BLOB 4#定义SQLITE_NULL 5

sqlite3_column_decltype（）例程返回文本，该文本是CREATE TABLE语句中声明的列类型。对于表达式，返回类型为空字符串。sqlite3_column_name（）返回第N列的名称。sqlite3_column_bytes（）返回类型为BLOB的列中的字节数或字节数使用UTF-8编码的TEXT字符串。sqlite3_column_bytes16（）返回BLOB的值相同，但TEXT字符串返回字节数UTF-16编码。sqlite3_column_blob（）返回blob数据。sqlite3_column_text（）将text数据返回为UTF-8。sqlite3_column_text16（）以UTF-16的形式返回TEXT数据。sqlite3_column_int（）在本机主机中返回INTEGER数据整数格式。sqlite3_column_int64（）返回64位整数数据。最后，sqlite3_column_double（）返回浮点数据。

不需要以指定的格式检索数据sqlite3_column_type（）。如果要求不同的格式自动转换。

数据格式转换可能会使之前调用sqlite3_column_blob（）、sqlite3_column_text（）和/或sqlite3_column_text16（）。指针可能在以下情况下无效案例：

注意UTF-16be和UTF-16le之间的转换总是在适当的地方完成不会使之前的指针无效，当然缓冲区的内容也是如此前面指针指向的将被修改。其他种类在可能的情况下进行转换，但有时确实如此不可能，在这种情况下，前面的指针无效。

最安全、最容易记住的策略是：假设结果来自

被后续调用无效这意味着您应该始终调用sqlite3_column_bytes（）或sqlite3_column_bytes16（）之前调用sqlite3_column_blob（），sqlite3_column_text（）或sqlite3_column_text16（）。

2.3用户定义的功能

可以使用以下例程创建用户定义的函数：

typedef结构sqlite3_value sqlite3_值；int sqlite3_create_function(方形3*，const char*zFunctionName，int n阿尔格，int eTextRep，无效*，void（*xFunc）（sqlite3_context*，int，sqlite3_value**），void（*xStep）（sqlite3_context*，int，sqlite3_value**），无效（*xFinal）（sqlite3_context*）);int sqlite3_create_function16(方形3*，const void*zFunctionName，int nArg中，int eTextRep，无效*，void（*xFunc）（sqlite3_context*，int，sqlite3_value**），void（*xStep）（sqlite3_context*，int，sqlite3_value**），无效（*xFinal）（sqlite3_context*）);#定义SQLITE_UTF8 1#定义SQLITE_UTF16 2#定义SQLITE_UTF16BE 3#定义SQLITE_UTF16LE 4#定义SQLITE_ANY 5

nArg参数指定函数的参数数量。值0表示允许任意数量的参数。这个eTextRep参数指定预期的表示文本值用于此函数的参数。此参数的值应该是上面定义的参数之一。SQLite版本3允许多个使用不同文本表示的相同函数的实现。数据库引擎选择最小化数字的函数需要进行个文本转换。

普通函数仅指定xFunc，并将xStep和xFinal设置为NULL。聚合函数指定xStep和xFinal，并将xFunc设置为NULL。没有单独的sqlite3_create_aggregate（）API。

函数名以UTF-8格式指定。单独的sqlite3_create_function16（）API的工作方式与sqlite_create_function（）相同但函数名是以UTF-16主机字节顺序指定的。

注意，函数的参数现在是指向sqlite3_value的指针结构，而不是像SQLite 2.X版中那样指向字符串的指针。以下例程用于从中提取有用信息“值”：

const void*sqlite3_value_blob（sqlite3_ value*）；int sqlite3_value_bytes（sqlite3_value*）；int sqlite3_value_bytes16（sqlite3_ value*）；双sqlite3_value_double（sqlite3~value*）；int sqlite3_value_int（sqlite3_值*）；long long int sqlite3_value_int64（sqlite3_ value*）；const unsigned char*sqlite3_value_text（sqlite3_value*）；const void*sqlite3_value_text16（sqlite3_值*）；int sqlite3_value_type（sqlite3_值*）；

函数实现使用以下API获取上下文和报告结果：

void*sqlite3_aggregate_context（sqlite3_context*，int nbyte）；无效*sqlite3_user_data（sqlite3_context*）；void sqlite3_result_blob（sqlite3_context*，const void*，int n，void（*）（void*））；无效sqlite3_result_double（sqlite3_context*，double）；void sqlite3_result_error（sqlite3_context*，const char*，int）；void sqlite3_result_error16（sqlite3_context*，const void*，int）；无效sqlite3_result_int（sqlite3_context*，int）；void sqlite3_result_int64（sqlite3_context*，long long int）；无效sqlite3_result_null（sqlite3_context*）；void sqlite3_result_text（sqlite3_context*，const char*，int n，void（*）（void*））；void sqlite3_result_text16（sqlite3_context*，const void*，int n，void（*）（void*））；无效sqlite3_result_value（sqlite3_context*，sqlite3_ value*）；void*sqlite3_get_auxdata（sqlite3_context*，int）；void sqlite3_set_auxdata（sqlite3_context*，int，void*，void（*）（void*））；

2.4用户定义的排序顺序

以下例程用于实现用户定义的排序序列：

sqlite3_create_collation（sqlite3*，const char*zName，int eTextRep，void*，int（*xCompare）（void*，int，const void*）；sqlite3_create_collation16（sqlite3*，const void*zName，int eTextRep，void*，int（*xCompare）（void*，int，const void*）；sqlite3_collation_needed（sqlite3*，void*，void（*）（void*，sqlite3*，int eTextRep，const char*）；sqlite3_collation_needed16（sqlite3*，void*，void（*）（void*，sqlite3*，int eTextRep，const void*）；

sqlite3_create_collation（）函数指定排序序列名以及一个比较函数来实现该排序序列。这个比较函数仅用于比较文本值。eTextRep参数是SQLITE_UTF8、SQLITE_UDF16LE、SQLITE_UTF16BE或SQLITE_ANY指定比较函数工作的文本表示带有。同一排序可以有单独的比较函数UTF-8、UTF-16LE和UTF-16BE文本表示中的每一个的序列。sqlite3_create_collation16（）的工作方式与sqlite3_create_colilation（）类似，但排序规则名称是以UTF-16主机字节顺序指定的，而不是UTF-8格式。

sqlite3_collation_needed（）例程注册一个回调如果遇到未知的排序序列，数据库引擎将调用。回调可以查找适当的比较函数并调用sqlite_3_create_collation（）。回调的第四个参数以UTF-8表示的排序序列的名称。对于sqlite3_collation_need16（）回调以UTF-16主机字节顺序发送排序序列名。