Sqlite3数据库常用API说明

    sqlite3的学习笔记:
        
    Sqilte是目前最流行的嵌入式数据库，其特点为占用资源少，管理简单，操作简单，生成的数据库文件很容易与各个平台兼容。    
    注意：
    1、因为Sqlite的数据管理机制更多依赖于OA文件系统，他不适用于网络传输的传输方式。
    2、受自身机制影响，Sqlite不适用于处理大数据与大数据存储。
    2、Sqlite只提供了表级锁，没有提供实际的锁机制，所以很难适用于高并发处理。
    
    在Sqlite提供了两个重要对象：database_connection和prepared_statement
    database_connection：
        1、database_connection对象是由sqlite3_open接口函数创建并返回的。
        2、在其他应用程序调用Sqlite3相关接口时，都需要这个对象作为输入来完成操作。
    prepared_statement：
        1、编译后的SQL语句。是select、insect、updata···
        2、所有和SQL语句执行相关的函数也都需要 该对象作为输入参数以完成指定的SQL操作。
        
    Sqlite3提供的常用API:
        注意：函数带有···v2的是Sqlite3提供的新版接口，没有的是旧版本接口。

1、

int sqlite3_open(

		  const char *filename,   /* Database filename (UTF-8) */

		  sqlite3 **ppDb          /* OUT: SQLite db handle */

		);

函数功能：打开一个操作数据库
    参数说明：
    filename：据库文件名称，若不存在，会自动创建。
    ppDb：重要数据结构的指针
    返回值：若打开或者创建成功，则会返回SQLITE_OK，否则会返回错误码。

2、

int sqlite3_close(sqlite3 *ppDb);

    函数功能：关闭一个执行完操作的数据库
    参数说明：
    ppDb：splite3_open操作时的第二个参数

3、

const char *sqlite3_errmsg(sqlite3*ppDb);

    函数功能：获取数据库操作错误时的错误码
    参数说明：
    ppDb：splite3_open操作时的第二个参数

4、

int sqlite3_exec(
	  sqlite3* ppDb,                             /* 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 */
	);

函数功能：执行sql指定的数据库命令操作。
    参数说明：
    ppDb：splite3_open操作时的第二个参数
    sql：SQL命令，可以有多条命令组成
    callback：执行完该函数的回调函数
    void *:作为callback回调函数的第一个参数传入
    errmsg:获取函数错误是的错误码
    注意：其实是sqlite3_exec在查询表的时候，每查到一条记录，就会调用一次回调函数，所以才是会显示出所有数据，而在插入，删除，更新执行一次。

5、

int sqlite_callback( 
　　void* pvoid, 
　　int argc, 
　　char** argv, 
　　char** col
); 

参数说明:
    pvoid:由 sqlite3_exec() 的第四个参数传递而来
    argc:表的列数或者记录中包含的字段数目
    argv：指向查询结果的指针数组, 可以由 sqlite3_column_text() 得到 ，包含每个字段值的指针数组
    col：指向表头名的指针数组, 可以由 sqlite3_column_name() 得到，包含每个字段名称的指针数组

6、

int sqlite3_get_table(
	  sqlite3 *ppDb,          /* An open database */
	  const char *zSql,     /* SQL to be evaluated */
	  char ***dbResult,     /* Results of the query */
	  int *pnRow,           /* Number of result rows written here */
	  int *pnColumn,        /* Number of result columns written here */
	  char **pzErrmsg       /* Error msg written here */
	);

    函数功能：获取数据库表格
    函数参数：
    ppDb：同上
    zSql：SQL命令
    dbResult：查询结果，它依然是一维数组，它内存布局是：字段名称，后面是紧接着是每个字段的值。
    pnRow：查出具体有多少行，即多少条记录（不包括字段名那行）。
    pnColumn：查出具体有多少列，即多少字段
    pzErrmsg：错误信息

7、

int sqlite3_prepare_v2(
	  sqlite3 *ppDb,            /* 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操作命令转换成一个准备对象，并返回这个对象的指针。
    参数说明：
    ppDb：同上
    zSql：SQL语句，新旧版本使用不同的编码
    nByte：若为负，从zSql中取出，直到第一个0终止符终止；如果为非负，它则是这个函数能读取Zsql的最大字节数。
    ppStmt：能够使用sqlite3_step()执行的编译好的准备语句的指针，如果错误发生，它被置为NULL，如假如输入的文本不包括SQL语句，调用过程必须负责在编译好的sql语句完成使用后使用sqlite3_finalize()删除它。
    pzTail:上面提到zSql在遇见终止符或者是达到设定的nByte之后结束，假如zSql还有剩余的内容，那么这些剩余的内容被存放到pZTail中，不包括终止符.

8、

int sqlite3_step(sqlite3_stmt*);

        函数功能：用于执行有前面sqlite3_prepare创建的准备语句，执行到结果的第一行可用的位置。需要前进到下一行，只需要继续调用sqlite3_step即可。
    那些不返回结果的语句（如：INSERT，UPDATE，或DELETE），sqlite3_step()只执行一次就返回。
    
    参数说明：
    sqlite3_stmt是结构体struct sqlite3_stmt变量。

9、

int sqlite3_reset(sqlite3_stmt *pStmt);

     函数功能：恢复一个对象，回到最初始的状态
    参数说明：同上

10、

int sqlite3_finalize(sqlite3_stmt *pStmt);

函数功能：销毁前面sqlite3_prepare_v2的准备语句，防止内存泄漏。

11、

const void *sqlite3_column_xxxx(sqlite3_stmt*, int iCol);//前缀函数

执行sqlite3_step执行一个准备语句得到的结果集的当前行中返回的一个列，但每次sqlite3_step执行完得到第一个结果集的列就停止，使用者类函数可以针对多列的情况。后面的后缀是要转换返回的类型。
        参数说明：
        sqlite3_stmt：同上
        iCol:返回列的索引，最左边的为0
        常见的函数：转换参考：https://blog.csdn.net/yishuige/article/details/52574569
                            http://www.yfvb.com/help/sqlite3/index.htm?page=sqlite3_column_blob.htm

const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);	//将列值作为blob返回。
		int sqlite3_column_bytes(sqlite3_stmt*, int iCol);			//返回列值的字节数
		int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);		//返回列值的字节数，UTF-16编码
		double sqlite3_column_double(sqlite3_stmt*, int iCol);		//返回值为double
		int sqlite3_column_int(sqlite3_stmt*, int iCol);			//返回列值为long。
		sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);//以四进制形式返回列值
		const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);//以UTF-8字符串的形式返回列值。
		const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);	//以UTF-16字符串的形式返回列值。
		int sqlite3_column_type(sqlite3_stmt*, int iCol);			//返回列类型
		sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);//返回列值作为指向不受保护的sqlite3_value对象的指针
		int sqlite3_column_count(sqlite3_stmt *pStmt);//返回准备语句返回的结果集中的列数。如果数PreparedStatementpstmt是不返回数据（例如UPDATE）的SQL语句，则此函数返回0。
		const char *sqlite3_column_decltype16(sqlite3_stmt*,int)	//返回查询结果的声明数据类型。
		int sqlite3_column_bytes(sqlite3_stmt*, int iCol)			//返回列值的字节数
		int sqlite3_column_bytes16(sqlite3_stmt*, int iCol)			//返回列值的字节数
		const char *sqlite3_column_database_name(sqlite3_stmt*,int);//返回数据库名称，它是SELECT语句中特定结果列的原点
		const char *sqlite3_column_origin_name(sqlite3_stmt*,int)	//返回作为SELECT语句中特定结果列的原点的列名。
		const char *column_table_name(sqlite3_stmt*,int);			//返回表名，它是SELECT语句中特定结果列的起始位置

    两个函数返回对应列的内容的字节数，这个字节数不包括后面类型转换过程中加上的0终止符。
        
        下面是几个最安全和最简单的使用策略
        先sqlite3_column_text() ，然后 sqlite3_column_bytes()
        先sqlite3_column_blob()，然后sqlite3_column_bytes()
        先sqlite3_column_text16()，然后sqlite3_column_bytes16()

12、

int sqlite3_bind_xxx绑定函数

函数功能：为语句对象增加数据
        常用的函数：参数说明见：http://www.sqlite.org/c3ref/bind_blob.html
        http://www.yfvb.com/help/sqlite3/index.htm?page=sqlite3_column_blob.htm

		int sqlite3_bind_blob（sqlite3_stmt *，int，const void *，int n，void（*）（void *））;
		int sqlite3_bind_blob64（sqlite3_stmt *，int，const void *，sqlite3_uint64，
								空隙（*）（无效*））;
		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，void（*）（void *））;
		int sqlite3_bind_text16（sqlite3_stmt *，int，const void *，int，void（*）（void *））;
		int sqlite3_bind_text64（sqlite3_stmt *，int，const char *，sqlite3_uint64，
								 void（*）（void *），unsigned char encoding）;
		int sqlite3_bind_value（sqlite3_stmt *，int，const sqlite3_value *）;
		int sqlite3_bind_pointer（sqlite3_stmt *，int，void *，const char *，void（*）（void *））;
		int sqlite3_bind_zeroblob（sqlite3_stmt *，int，int n）;
		int sqlite3_bind_zeroblob64（sqlite3_stmt *，int，sqlite3_uint64）;

        在输入sqlite3_prepare_v2（）及其变体的SQL语句文本中，文字可能会被匹配以下模板之一的参数替换：
        ·？
        ·？NNN
        ·：VVV
        ·@VVV
        ·$ VVV
    在上面的模板中，NNN表示整数文字，VVV表示字母数字标识符。可以使用此处定义的sqlite3_bind（）例程来设置这些参数的值（也称为“主机参数名称”或“SQL参数”）。
        
        参数说明：
        第一个参数：指向sqlite3_prepare_v2（）或其变体返回的sqlite3_stmt对象的指针
        第二个参数：要设置的SQL参数的索引。最左边的SQL参数的索引为1.当同一个命名的SQL参数被多次使用时，第二次和后续出现的索引与第一次出现的索引相同。如果需要，可以使用sqlite3_bind_parameter_index（） API查找命名参数的索引 。“？NNN”参数的索引是NNN的值。NNN值必须介于1和sqlite3_limit（） 参数SQLITE_LIMIT_VARIABLE_NUMBER之间（默认值：999）。
        第三个参数：绑定到参数的值。
        如果sqlite3_bind_text（）或sqlite3_bind_text16（）或sqlite3_bind_blob（）的第三个参数是NULL指针，则忽略第四个参数，最终结果与sqlite3_bind_null（）相同。
        第四个参数：针对有这个参数的函数而言，其值是参数中的字节数。要清楚：值是字节数在值中，而不是字符数。
        如果sqlite3_bind_text（）或sqlite3_bind_text16（）的第四个参数为负，则字符串的长度是直到第一个零终止符的字节数。
        如果向sqlite3_bind_text（）或sqlite3_bind_text16（）或sqlite3_bind_text64（）提供了非负第四个参数，则该参数必须是假定字符串NUL终止时NUL终结符将发生的字节偏移量，如果在字节偏移小于第四个参数的值时出现任何NUL字符，则结果字符串值将包含嵌入的NUL。涉及具有嵌入式NUL的字符串的表达式的结果是未定义的。
        如果sqlite3_bind_blob（）的第四个参数为负数，则行为未定义。
        
        第五个参数：针对有第五个参数的blob而言。是一个析构函数，用于在SQLite完成后处理BLOB或字符串。即使对绑定API的调用失败，也会调用析构函数来处理BLOB或字符串，但如果第三个参数是NULL指针或第四个参数为负，则不会调用析构函数。如果第五个参数是特殊值SQLITE_STATIC，那么SQLite假定信息在静态的非托管空间中，并且不需要释放。如果第五个参数的值为SQLITE_TRANSIENT，则SQLite会在sqlite3_bind _ *（）例程返回之前立即创建自己的数据私有副本。
    
        第六个参数：指定编码
        sqlite3_bind_text64（）的第六个参数必须是 SQLITE_UTF8，SQLITE_UTF16，SQLITE_UTF16BE或SQLITE_UTF16LE之一， 以指定第三个参数中文本的编码。如果sqlite3_bind_text64（）的第六个参数不是上面显示的允许值之一，或者如果文本编码与第六个参数指定的编码不同，则行为未定义。

        注意：
        1、在批量插入数据时，执行一次sqlite3_prepare_v2比sqlite3_step消耗的时间多得多，因此应该尽量避免重复调用sqlite3_prepare_v2。在我们的实现中，如果想避免此类开销，只需将待插入的数据以变量的形式绑定到SQL语句中，这样该SQL语句仅需调用sqlite3_prepare_v2函数编译一次即可，其后的操作只是替换 不同的变量数值。
        2、SQL语句"insert into testtable values(?)"中的问号(?)表示参数变量的占位符，该规则在很多关系型数据库中都是一致的，因此这对于数据库移植操作还是比较方便的。