使用demo:点击打开链接
使用的过程根据使用的函数大致分为如下几个过程:
这几个过程是概念上的说法,而不完全是程序运行的过程,如sqlite3_column()表示的是对查询获得一行里面的数据的列的各个操作统称,实际上在sqlite中并不存在这个函数。
在操作数据库之前,首先要打开数据库。这个函数打开一个sqlite数据库文件的连接并且返回一个数据库连接对象。这个操作同时程序中的第一个调用的sqlite函数,同时也是其他sqliteapi的先决条件。许多的sqlite接口函数都需要一个数据库连接对象的指针作为它们的第一个参数。
函数定义
int sqlite3_open(const char*filename,sqlite3**ppDb );
int sqlite3_open16(const void*filename,sqlite3**ppD);
int sqlite3_open_v2(const char*filename,sqlite3**ppDb,intflags,const char*zVfs );
说明:
假如这个要被打开的数据文件不存在,则一个同名的数据库文件将被创建。如果使用sqlite3_open和sqlite3_open_v2的话,数据库将采用UTF-8的编码方式,sqlite3_open16采用UTF-16的编码方式
返回值:
如果sqlite数据库被成功打开(或创建),将会返回sqlITE_OK,否则将会返回错误码。sqlite3_errmsg()或者sqlite3_errmsg16可以用于获得数据库打开错误码的英文描述,这两个函数定义为:
const char *sqlite3_errmsg(sqlite3*);
const void *sqlite3_errmsg16(sqlite3*);
无论是否成功打开数据库,都应该使用 sqlite3_close() 关闭数据库连接.
参数说明:
filename:需要被打开的数据库文件的文件名,在sqlite3_open和sqlite3_open_v2中这个参数采用UTF-8编码,而在sqlite3_open16中则采用UTF-16编码
ppDb:一个数据库连接句柄被返回到这个参数,即使发生错误。唯一的一场是如果sqlite不能分配内存来存放sqlite对象,ppDb将会被返回一个NULL值。
flags:作为数据库连接的额外控制的参数,可以是sqlITE_OPEN_READONLY,sqlITE_OPEN_READWRITE和sqlITE_OPEN_READWRITE|sqlITE_OPEN_CREATE中的一个,用于控制数据库的打开方式,可以和SQLITE_OPEN_NOMUTEX,SQLITE_OPEN_FULLMUTEX,
=====================================================================================
2.
这个函数将sql文本转换成一个准备语句(prepared statement)对象,同时返回这个对象的指针。这个接口需要一个数据库连接指针以及一个要准备的包含sql语句的文本。它实际上并不执行(evaluate)这个sql语句,它仅仅为执行准备这个sql语句
函数定义(仅列出UTF-8的)
int sqlite3_prepare(sqlite3*db,const char*zsql,intnByte,sqlite3_stmt**ppStmt,const char**pzTail );int sqlite3_prepare_v2(sqlite3*db,sqlite3_stmt **ppStmt,const char**pzTail);
参数:
db:数据指针
nByte:如果nByte小于0,则函数取出zsql中从开始到第一个0终止符的内容;如果nByte不是负的,那么它就是这个函数能从zsql中读取的字节数的最大值。如果nBytes非负,zsql在第一次遇见’/000/或’u000’的时候终止.如果用户知道被传入的 sql语句是以 '\0' 结尾的,那么有一个更好的做法是:把nbytes的值设为该字符串的长度(包含'\0'),这样可以避免sqlite 复制该字符串的一份拷贝,以提高程序的效率.
pzTail:上面提到zsql在遇见终止符或者是达到设定的nByte之后结束,假如zsql还有剩余的内容,那么这些剩余的内容被存放到pZTail中,不包括终止符。如果 pszTail 不为 NULL,则 *pszTail 指向 sql 中第一个被传入的 sql语句的结尾. 该函数只编译 sql 的第一个语句,所以 *pszTail 指向的内容则是未被编译的.
ppStmt:能够使用sqlite3_step()执行的编译好的准备语句的指针,如果错误发生,它被置为NULL,如假如输入的文本不包括sql语句。调用过程必须负责在编译好的sql语句完成使用后使用sqlite3_finalize()删除它。
说明
如果执行成功,则返回sqlITE_OK,否则返回一个错误码。推荐在现在任何的程序中都使用sqlite3_prepare_v2这个函数,sqlite3_prepare只是用于前向兼容
备注
<1>准备语句(preparedstatement)对象
typedef struct sqlite3_stmtsqlite3_stmt;
准备语句(preparedstatement)对象一个代表一个简单sql语句对象的实例,这个对象通常被称为“准备语句”或者“编译好的sql语句”或者就直接称为“语句”。
l
l
l
l
l
在sqlite中并没有定义sqlite3_stmt这个结构的具体内容,它只是一个抽象类型,在使用过程中一般以它的指针进行操作,而sqlite3_stmt类型的指针在实际上是一个指向Vdbe的结构体得指针
<2>宿主参数(host parameters)
在传给sqlite3_prepare_v2()的sql的语句文本或者它的变量中,满足如下模板的文字将被替换成一个参数:
l
l
l
l
l
在上面这些模板中,NNN代表一个数字,VVV代表一个字母数字标记符(例如:222表示名称为222的标记符),sql语句中的参数(变量)通过上面的几个模板来指定,如
“select ? from ?“这个语句中指定了两个参数,sqlite语句中的第一个参数的索引值是1,这就知道这个语句中的两个参数的索引分别为1和2,使用”?”的话会被自动给予索引值,而使用”?NNN”则可以自己指定参数的索引值,它表示这个参数的索引值为NNN。”:VVV”表示一个名为”VVV”的参数,它也有一个索引值,被自动指定。
例子:
INSERT
INSERT
INSERT
INSERT
INSERT
可以使用sqlite3_bind_*()来给这些参数绑定值
=====================================================================================
3.
int sqlite3_bind_text(sqlite3_stmt*,int,const char*,intn,void(*)(void*));
sqlite3_bind_*系列函数有好多,这里只对sqlite3_bind_text进行一下说明,sqlite3_bind_text的第二个参数为序号(从1开始),第三个参数为字符串值,第四个参数为字符串长度。sqlite3_bind_text的第五个参数为一个函数指针,sqlITE3执行完操作后回调此函数,通常用于释放字符串占用的内存。此参数有两个常数,sqlITE_STATIC告诉sqlite3_bind_text函数字符串为常量,可以放心使用;而sqlITE_TRANSIENT会使得sqlite3_bind_text函数对字符串做一份拷贝。一般使用这两个常量参数来调sqlite3_bind_text。statement准备好了以后,就是操作的执行了。
功能:为查询结构体绑定数据
PARAM1(IN):查询结构体
PARAM2(IN):绑定第几个数据(sql语句中的第几个问号(?))
PARAM3(IN):二进制数据指针
PARAM4(IN):二进制数据长度
PARAM5(IN):析构回调函数,通常设置NULL,结束后自己释放
返回值:sqlITE_OK成功.
说明:绑定函数必须要在sqlite3_step前,sqlite3_prepare或者sqlite3_reset之后调用.
未绑定的参数缺省为NULL,类似的绑定函数还有以下
int sqlite3_bind_double(sqlite3_stmt*,double);
int sqlite3_bind_int(sqlite3_stmt*,int);
int sqlite3_bind_int64(sqlite3_stmt*,sqlite_int64);
int sqlite3_bind_null(sqlite3_stmt*,int);
int sqlite3_bind_text(sqlite3_stmt*,void(*)(void*));
int sqlite3_bind_text16(sqlite3_stmt*,void(*)(void*));
int sqlite3_bind_value(sqlite3_stmt*,const sqlite3_value*);
=====================================================================================
4.
这个过程用于执行有前面sqlite3_prepare创建的准备语句。这个语句执行到结果的第一行可用的位置。继续前进到结果的第二行的话,只需再次调用sqlite3_setp()。继续调用sqlite3_setp()知道这个语句完成,那些不返回结果的语句(如:INSERT,UPDATE,或DELETE),sqlite3_step()只执行一次就返回
函数定义
int sqlite3_step(sqlite3_stmt*);
返回值
函数的返回值基于创建sqlite3_stmt参数所使用的函数,假如是使用老版本的接口sqlite3_prepare()和sqlite3_prepare16(),返回值会是
对所有V3.6.23.1以及其前面的所有版本,需要在sqlite3_step()之后调用sqlite3_reset(),在后续的sqlite3_ step之前。如果调用sqlite3_reset重置准备语句失败,将会导致sqlite3_step返回sqlITE_MISUSE,但是在V3.6.23.1以后,sqlite3_step()将会自动调用sqlite3_reset。
说明:
其它:
=====================================================================================
5.int sqlite3_reset(sqlite3_stmt *pStmt);
sqlite3_reset用于重置一个准备语句对象到它的初始状态,然后准备被重新执行。所有sql语句变量使用sqlite3_bind*绑定值,使用sqlite3_clear_bindings重设这些绑定。sqlite3_reset接口重置准备语句到它代码开始的时候。sqlite3_reset并不改变在准备语句上的任何绑定值,那么这里猜测,可能是语句在被执行的过程中发生了其他的改变,然后这个语句将它重置到绑定值的时候的那个状态。
const unsigned char *sqlite3_column_text(sqlite3_stmt*,intiCol);
其中参数iCol为列的序号,从0开始。如果返回值有多行,则可以再次调用sqlite3_step函数,然后由sqlite3_column_*函数取得返回值。使用上述这些函数基本上可以完成对sqlITE3数据库的操作了(不过我这里只针对text数据类型做了说明)。
=====================================================================================
6.
这个过程从执行sqlite3_step()执行一个准备语句得到的结果集的当前行中返回一个列。每次sqlite3_step得到一个结果集的列停下后,这个过程就可以被多次调用去查询这个行的各列的值。对列操作是有多个函数,均以sqlite3_column为前缀
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*,intiCol);
const void *sqlite3_column_text16(sqlite3_stmt*,int iCol);
int sqlite3_column_type(sqlite3_stmt*,int iCol);
int sqlite3_column_numeric_type(sqlite3_stmt*,intiCol);
sqlite3_value *sqlite3_column_value(sqlite3_stmt*,intiCol);
说明
第一个参数为从sqlite3_prepare返回来的preparedstatement对象的指针,第二参数指定这一行中的想要被返回的列的索引。最左边的一列的索引号是0,行的列数可以使用sqlite3_colum_count()获得。
这些过程会根据情况去转换数值的类型,sqlite内部使用sqlite3_snprintf()去自动进行这个转换,下面是关于转换的细节表:
内部类型 |
请求的类型 |
转换 |
NULL |
INTEGER |
结果是0 |
NULL |
FLOAT |
结果是0.0 |
NULL |
TEXT |
结果是NULL |
NULL |
BLOB |
结果是NULL |
INTEGER |
FLOAT |
从整形转换到浮点型 |
INTEGER |
TEXT |
整形的ASCII码显示 |
INTEGER |
BLOB |
同上 |
FLOAT |
INTEGER |
浮点型转换到整形 |
FLOAT |
TEXT |
浮点型的ASCII显示 |
FLOAT |
BLOB |
同上 |
TEXT |
INTEGER |
使用atoi() |
TEXT |
FLOAT |
使用atof() |
TEXT |
BLOB |
没有转换 |
BLOB |
INTEGER |
先到TEXT,然后使用atoi |
BLOB |
FLOAT |
先到TEXT,然后使用atof |
BLOB |
TEXT |
如果需要的话添加0终止符 |
注:BLOB数据类型是指二进制的数据块,比如要在数据库中存放一张图片,这张图片就会以二进制形式存放,在sqlite中对应的数据类型就是BLOB
int sqlite3_column_bytes(sqlite3_stmt*,int iCol)intsqlite3_column_bytes16(sqlite3_stmt*,intiCol)两个函数返回对应列的内容的字节数,这个字节数不包括后面类型转换过程中加上的0终止符。
下面是几个最安全和最简单的使用策略
- 先sqlite3_column_text() ,然后 sqlite3_column_bytes()
- 先sqlite3_column_blob(),然后sqlite3_column_bytes()
- 先sqlite3_column_text16(),然后sqlite3_column_bytes16()
得到数据行中某个列的数据 sqlite3_column_xxx(sqlite3_stmt*,int iCol); 在sqlite3_step返回sqlITE_ROW后,使用它得到第iCol列的数据。 其中的xxx代表: blob:指向保存数据内存的指针 bytes,bytes16: 得到该blob类型数据的大小,或者text转换为UTF8/UTF16的字符串长度。 double,int64: 数值 text,text16:字符串指针 type:该列的数据类型(sqlITE_INTEGER,sqlITE_FLOAT,sqlITE_TEXT,sqlITE_BLOB,sqlITE_NULL) 注意:如果对该列使用了不同与该列本身类型适合的数据读取方法,得到的数值将是转换过的结果。
(2)
得到数据行中某个列的数据的类型 int sqlite3_column_type(sqlite3_stmt*,int iCol); 返回值:sqlITE_INTEGER,sqlITE_FLOAT,sqlITE_TEXT,sqlITE_BLOB,sqlITE_NULL 使用的方法和sqlite3_column_xxx()函数类似。
(3)
int sqlite3_column_count(sqlite3_stmt *pStmt);
功能:获取列数
如果过程没有返回值,如update,将返回0
const char *sqlite3_column_name(sqlite3_stmt*,int);
功能:获取列名
const char *sqlite3_column_decltype(sqlite3_stmt *,inti);
功能:返回列数据类型
类似:
得到当前行中包含的数据个数 int sqlite3_data_count(sqlite3_stmt *pStmt); 如果sqlite3_step返回sqlITE_ROW,可以得到列数,否则为零。
=====================================================================================
7.int sqlite3_reset(sqlite3_stmt *pStmt);
功能:重置所有绑定的值,回到刚刚调用sqlite3_prepare后的状态
=====================================================================================
8.sqlite3_finalize
这个过程销毁前面被sqlite3_prepare创建的准备语句,每个准备语句都必须使用这个函数去销毁以防止内存泄露。
在空指针上调用这个函数没有什么影响,同时可以准备语句的生命周期的任一时刻调用这个函数:在语句被执行前,一次或多次调用sqlite_reset之后,或者在sqlite3_step任何调用之后不管语句是否完成执行
示例:=====================================================================================
9.sqlite3_close
这个过程关闭前面使用sqlite3_open打开的数据库连接,任何与这个连接相关的准备语句必须在调用这个关闭函数之前被释放
int sqlite3_close(
说明:
应用程序必须在关闭之前 "完成(finalize)" 所有的 "预编译语句(prepared statements)",并且关闭所有的 "二进制句柄绑定(BLOB handle)",如果在关闭时还有未完成的预编译语句或二进制句柄,那么函数返回sqlITE_BUSY(5).
示例:
=====================================================================================
10.int sqlite3_exec(
);
说明:
示例:
参阅:在 sqlite3中使用回调函数(http://www.cnblogs.com/nbsofer/archive/2012/05/29/2523807.html)
=====================================================================================
11.int sqlite3_errcode(
);
说明:
示例:
=====================================================================================
12.const char *sqlite3_errmsg(
);
说明:
示例:
13.
=====================================================================================
int sqlite3_key(
);
功能:为加密的数据库指定密码,改函数在sqlite3_open之后调用
14.
=====================================================================================
int sqlite3_rekey(
);
功能:重设数据库密码,如果pKey = 0 或者 nKey = 0,这数据库不加密
=====================================================================================
15.
=====================================================================================
int sqlite3_get_table(
);
功能:查询表
PARAM1(IN):数据库句柄
PARAM2(IN):sql语句,以\0结尾.
PARAM3(OUT):查询结果
PARAM4(OUT):返回行数(多少条数据)
PARAM5(OUT):返回列数(多少字段)
PARAM6(OUT):返回错误信息
返回值:sqlITE_OK成功,房子失败见错误信息
16.
=====================================================================================
void sqlite3_free_table(char **result);
功能:释放通过sqlite3_get_table查询保存的结果数据
PARAM1(IN):要释放的数据指针
=====================================================================================
17.int sqlite3_create_function(
);
功能:
const void *sqlite3_value_blob(sqlite3_value*);
int sqlite3_value_bytes(sqlite3_value*);
int sqlite3_value_bytes16(sqlite3_value*);
double sqlite3_value_double(sqlite3_value*);
int sqlite3_value_int(sqlite3_value*);
sqlite_int64 sqlite3_value_int64(sqlite3_value*);
const unsigned char *sqlite3_value_text(sqlite3_value*);
const void *sqlite3_value_text16(sqlite3_value*);
const void *sqlite3_value_text16le(sqlite3_value*);
const void *sqlite3_value_text16be(sqlite3_value*);
int sqlite3_value_type(sqlite3_value*);
int sqlite3_value_numeric_type(sqlite3_value*);
功能:类似sqlite3_column_*函数
其他:
const char *sqlite3_libversion(void);
int sqlite3_libversion_number(void);
功能:获取版本号
sqlite_int64 sqlite3_last_insert_rowid(sqlite3*);
功能:获取最后插入的行标示.
int sqlite3_changes(sqlite3*);
功能:获取最近执行的sqlite3_exec影响的行数.
int sqlite3_total_changes(sqlite3*);
功能:获取自从数据库打开后有改动的函数
void sqlite3_interrupt(sqlite3*);
功能:打断或停止数据库当前操作.
int sqlite3_complete(const char *sql);
功能:判断语句是否以分号(;)结尾
int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*);
功能:设置查询忙碌时的回调处理
说明:缺省的回调函数为空,如果回调函数为空,表锁定后sqlite3_exec()执行会直接返回sqlITE_BUSY
int sqlite3_busy_timeout(sqlite3*,int ms);
功能:设置查询超时时间(毫秒)
char *sqlite3_mprintf(const char*,...);
char *sqlite3_vmprintf(const char*,va_list);
char *sqlite3_snprintf(int,char*,...);
功能:格式化字符,需要用%q来代替%s.(主要是不用对分号'进行转义)
void *sqlite3_malloc(int);
void *sqlite3_realloc(void*,int);
void sqlite3_free(void*);
功能:内存函数
int sqlite3_set_authorizer(
);
功能:设置数据库授权
void *sqlite3_trace(sqlite3*,void(*xTrace)(void*,void*);
void *sqlite3_profile(sqlite3*,
void sqlite3_progress_handler(sqlite3*,int(*)(void*),void*);
功能:设置执行回调函数,sqlite3_exec(),sqlite3_step(),sqlite3_get_table()时会调用
void *sqlite3_commit_hook(sqlite3*,void*);
功能:设置事务回调函数
int sqlite3_errcode(sqlite3 *db);
const char *sqlite3_errmsg(sqlite3*);
功能:获取错误码和错误消息
int sqlite3_bind_parameter_count(sqlite3_stmt*);
功能:返回需要绑定的参数数目(sql语句中问号?数量)
const char *sqlite3_bind_parameter_name(sqlite3_stmt*,int);
功能:获取绑定参数名字,?参数返回NULL
int sqlite3_bind_parameter_index(sqlite3_stmt*,const char*zName);
功能:获取绑定参数索引
int sqlite3_clear_bindings(sqlite3_stmt*);
功能:清除绑定的参数
参考代码:
#include
#include "sqlite3.h"
int main(){