1.0 總覽
SQLite3是SQLite一個(gè)全新的版本,它雖然是在SQLite 2.8.13的代碼基礎(chǔ)之上開(kāi)發(fā)的,但是使用了和之前的版本不兼容的數(shù)據(jù)庫(kù)格式和API. SQLite3是為了滿足以下的需求而開(kāi)發(fā)的:
l 支持UTF-16編碼.
l 用戶自定義的文本排序方法.
l 可以對(duì)BLOBs字段建立索引.
因此為了支持這些特性我改變了數(shù)據(jù)庫(kù)的格式,建立了一個(gè)與之前版本不兼容的3.0版. 至于其他的兼容性的改變,例如全新的API等等,都將在理論介紹之后向你說(shuō)明,這樣可以使你最快的一次性擺脫兼容性問(wèn)題.
3.0版的和2.X版的API非常相似,但是有一些重要的改變需要注意. 所有API接口函數(shù)和數(shù)據(jù)結(jié)構(gòu)的前綴都由"sqlite_"改為了"sqlite3_". 這是為了避免同時(shí)使用SQLite 2.X和SQLite 3.0這兩個(gè)版本的時(shí)候發(fā)生鏈接沖突.
由于對(duì)于C語(yǔ)言應(yīng)該用什么數(shù)據(jù)類型來(lái)存放UTF-16編碼的字符串并沒(méi)有一致的規(guī)范. 因此SQLite使用了普通的void* 類型來(lái)指向UTF-16編碼的字符串. 客戶端使用過(guò)程中可以把void*映射成適合他們的系統(tǒng)的任何數(shù)據(jù)類型.
2.0 C/C++ 接口
SQLite 3.0一共有83個(gè)API函數(shù),此外還有一些數(shù)據(jù)結(jié)構(gòu)和預(yù)定義(#defines). (完整的API介紹請(qǐng)參看另一份文檔.) 不過(guò)你們可以放心,這些接口使用起來(lái)不會(huì)像它的數(shù)量所暗示的那么復(fù)雜. 最簡(jiǎn)單的程序仍然使用三個(gè)函數(shù)就可以完成: sqlite3_open(), sqlite3_exec(), 和 sqlite3_close(). 要是想更好的控制數(shù)據(jù)庫(kù)引擎的執(zhí)行,可以使用提供的sqlite3_prepare()函數(shù)把SQL語(yǔ)句編譯成字節(jié)碼,然后在使用sqlite3_step()函數(shù)來(lái)執(zhí)行編譯后的字節(jié)碼. 以sqlite3_column_開(kāi)頭的一組API函數(shù)用來(lái)獲取查詢結(jié)果集中的信息. 許多接口函數(shù)都是成對(duì)出現(xiàn)的,同時(shí)有UTF-8和UTF-16兩個(gè)版本. 并且提供了一組函數(shù)用來(lái)執(zhí)行用戶自定義的SQL函數(shù)和文本排序函數(shù).
2.1 如何打開(kāi)關(guān)閉數(shù)據(jù)庫(kù)
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() 函數(shù)返回一個(gè)整數(shù)錯(cuò)誤代碼,而不是像第二版中一樣返回一個(gè)指向sqlite3結(jié)構(gòu)體的指針. sqlite3_open() 和 sqlite3_open16() 的不同之處在于sqlite3_open16() 使用UTF-16編碼(使用本地主機(jī)字節(jié)順序)傳遞數(shù)據(jù)庫(kù)文件名. 如果要?jiǎng)?chuàng)建新數(shù)據(jù)庫(kù), sqlite3_open16() 將內(nèi)部文本轉(zhuǎn)換為UTF-16編碼, 反之sqlite3_open() 將文本轉(zhuǎn)換為UTF-8編碼.
打開(kāi)或者創(chuàng)建數(shù)據(jù)庫(kù)的命令會(huì)被緩存,直到這個(gè)數(shù)據(jù)庫(kù)真正被調(diào)用的時(shí)候才會(huì)被執(zhí)行. 而且允許使用PRAGMA聲明來(lái)設(shè)置如本地文本編碼或默認(rèn)內(nèi)存頁(yè)面大小等選項(xiàng)和參數(shù).
sqlite3_errcode() 通常用來(lái)獲取最近調(diào)用的API接口返回的錯(cuò)誤代碼. sqlite3_errmsg() 則用來(lái)得到這些錯(cuò)誤代碼所對(duì)應(yīng)的文字說(shuō)明. 這些錯(cuò)誤信息將以 UTF-8 的編碼返回,并且在下一次調(diào)用任何SQLite API函數(shù)的時(shí)候被清除. sqlite3_errmsg16() 和 sqlite3_errmsg() 大體上相同,除了返回的錯(cuò)誤信息將以 UTF-16 本機(jī)字節(jié)順序編碼.
SQLite3的錯(cuò)誤代碼相比SQLite2沒(méi)有任何的改變,它們分別是:
#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.2 執(zhí)行 SQL 語(yǔ)句
typedef int (*sqlite_callback)(void*,int,char**, char**);
int sqlite3_exec(sqlite3*, const char *sql, sqlite_callback, void*, char**);
sqlite3_exec 函數(shù)依然像它在SQLite2中一樣承擔(dān)著很多的工作. 該函數(shù)的第二個(gè)參數(shù)中可以編譯和執(zhí)行零個(gè)或多個(gè)SQL語(yǔ)句. 查詢的結(jié)果返回給回調(diào)函數(shù). 更多地信息可以查看API 參考.
在SQLite3里,sqlite3_exec一般是被準(zhǔn)備SQL語(yǔ)句接口封裝起來(lái)使用的.
typedef struct sqlite3_stmt sqlite3_stmt;
int sqlite3_prepare(sqlite3*, const char*, int, sqlite3_stmt**, const char**);
int sqlite3_prepare16(sqlite3*, const void*, int, sqlite3_stmt**, const void**);
int sqlite3_finalize(sqlite3_stmt*);
int sqlite3_reset(sqlite3_stmt*);
sqlite3_prepare 接口把一條SQL語(yǔ)句編譯成字節(jié)碼留給后面的執(zhí)行函數(shù). 使用該接口訪問(wèn)數(shù)據(jù)庫(kù)是當(dāng)前比較好的的一種方法.
sqlite3_prepare() 處理的SQL語(yǔ)句應(yīng)該是UTF-8編碼的. 而sqlite3_prepare16() 則要求是UTF-16編碼的. 輸入的參數(shù)中只有第一個(gè)SQL語(yǔ)句會(huì)被編譯. 第四個(gè)參數(shù)則用來(lái)指向輸入?yún)?shù)中下一個(gè)需要編譯的SQL語(yǔ)句存放的SQLite statement對(duì)象的指針, 任何時(shí)候如果調(diào)用 sqlite3_finalize() 將銷毀一個(gè)準(zhǔn)備好的SQL聲明. 在數(shù)據(jù)庫(kù)關(guān)閉之前，所有準(zhǔn)備好的聲明都必須被釋放銷毀. sqlite3_reset() 函數(shù)用來(lái)重置一個(gè)SQL聲明的狀態(tài)，使得它可以被再次執(zhí)行.
SQL聲明可以包含一些型如"?" 或 "?nnn" 或 ":aaa"的標(biāo)記，其中"nnn" 是一個(gè)整數(shù)，"aaa" 是一個(gè)字符串. 這些標(biāo)記代表一些不確定的字符值（或者說(shuō)是通配符），可以在后面用sqlite3_bind 接口來(lái)填充這些值. 每一個(gè)通配符都被分配了一個(gè)編號(hào)（由它在SQL聲明中的位置決定，從1開(kāi)始），此外也可以用 "nnn" 來(lái)表示 "?nnn" 這種情況. 允許相同的通配符在同一個(gè)SQL聲明中出現(xiàn)多次, 在這種情況下所有相同的通配符都會(huì)被替換成相同的值. 沒(méi)有被綁定的通配符將自動(dòng)取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 所包含的全部接口，它們是用來(lái)給SQL聲明中的通配符賦值的. 沒(méi)有綁定的通配符則被認(rèn)為是空值. 綁定上的值不會(huì)被sqlite3_reset()函數(shù)重置. 但是在調(diào)用了sqlite3_reset()之后所有的通配符都可以被重新賦值.
在SQL聲明準(zhǔn)備好之后(其中綁定的步驟是可選的), 需要調(diào)用以下的方法來(lái)執(zhí)行:
int sqlite3_step(sqlite3_stmt*);
如果SQL返回了一個(gè)單行結(jié)果集，sqlite3_step() 函數(shù)將返回 SQLITE_ROW , 如果SQL語(yǔ)句執(zhí)行成功或者正常將返回 SQLITE_DONE , 否則將返回錯(cuò)誤代碼. 如果不能打開(kāi)數(shù)據(jù)庫(kù)文件則會(huì)返回 SQLITE_BUSY . 如果函數(shù)的返回值是 SQLITE_ROW, 那么下邊的這些方法可以用來(lái)獲得記錄集行中的數(shù)據(jù):
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);
double 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()函數(shù)返回結(jié)果集中包含的列數(shù). sqlite3_column_count() 可以在執(zhí)行了 sqlite3_prepare()之后的任何時(shí)刻調(diào)用. sqlite3_data_count()除了必需要在sqlite3_step()之后調(diào)用之外，其他跟sqlite3_column_count() 大同小異. 如果調(diào)用sqlite3_step() 返回值是 SQLITE_DONE 或者一個(gè)錯(cuò)誤代碼, 則此時(shí)調(diào)用sqlite3_data_count() 將返回 0 ，然而 sqlite3_column_count() 仍然會(huì)返回結(jié)果集中包含的列數(shù).
返回的記錄集通過(guò)使用其它的幾個(gè) sqlite3_column_***() 函數(shù)來(lái)提取, 所有的這些函數(shù)都把列的編號(hào)作為第二個(gè)參數(shù). 列編號(hào)從左到右以零起始. 請(qǐng)注意它和之前那些從1起始的參數(shù)的不同.
sqlite3_column_type()函數(shù)返回第N列的值的數(shù)據(jù)類型. 具體的返回值如下:
#define SQLITE_INTEGER 1
#define SQLITE_FLOAT 2
#define SQLITE_TEXT 3
#define SQLITE_BLOB 4
#define SQLITE_NULL 5
sqlite3_column_decltype() 則用來(lái)返回該列在 CREATE TABLE 語(yǔ)句中聲明的類型. 它可以用在當(dāng)返回類型是空字符串的時(shí)候. sqlite3_column_name() 返回第N列的字段名. sqlite3_column_bytes() 用來(lái)返回 UTF-8 編碼的BLOBs列的字節(jié)數(shù)或者TEXT字符串的字節(jié)數(shù). sqlite3_column_bytes16() 對(duì)于BLOBs列返回同樣的結(jié)果，但是對(duì)于TEXT字符串則按 UTF-16 的編碼來(lái)計(jì)算字節(jié)數(shù). sqlite3_column_blob() 返回 BLOB 數(shù)據(jù). sqlite3_column_text() 返回 UTF-8 編碼的 TEXT 數(shù)據(jù). sqlite3_column_text16() 返回 UTF-16 編碼的 TEXT 數(shù)據(jù). sqlite3_column_int() 以本地主機(jī)的整數(shù)格式返回一個(gè)整數(shù)值. sqlite3_column_int64() 返回一個(gè)64位的整數(shù). 最后, sqlite3_column_double() 返回浮點(diǎn)數(shù).
不一定非要按照sqlite3_column_type()接口返回的數(shù)據(jù)類型來(lái)獲取數(shù)據(jù). 數(shù)據(jù)類型不同時(shí)軟件將自動(dòng)轉(zhuǎn)換.
2.3 用戶自定義函數(shù)
可以使用以下的方法來(lái)創(chuàng)建用戶自定義的SQL函數(shù):
typedef struct sqlite3_value sqlite3_value;
int sqlite3_create_function(
sqlite3 *,
const char *zFunctionName,
int nArg,
int eTextRep,
void*,
void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
void (*xStep)(sqlite3_context*,int,sqlite3_value**),
void (*xFinal)(sqlite3_context*)
);
int sqlite3_create_function16(
sqlite3*,
const void *zFunctionName,
int nArg,
int eTextRep,
void*,
void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
void (*xStep)(sqlite3_context*,int,sqlite3_value**),
void (*xFinal)(sqlite3_context*)
);
#define SQLITE_UTF8 1
#define SQLITE_UTF16 2
#define SQLITE_UTF16BE 3
#define SQLITE_UTF16LE 4
#define SQLITE_ANY 5
nArg 參數(shù)用來(lái)表明自定義函數(shù)的參數(shù)個(gè)數(shù). 如果參數(shù)值為0，則表示接受任意個(gè)數(shù)的參數(shù). 用 eTextRep 參數(shù)來(lái)表明傳入?yún)?shù)的編碼形式. 參數(shù)值可以是上面的五種預(yù)定義值. SQLite3 允許同一個(gè)自定義函數(shù)有多種不同的編碼參數(shù)的版本. 數(shù)據(jù)庫(kù)引擎會(huì)自動(dòng)選擇轉(zhuǎn)換參數(shù)編碼個(gè)數(shù)最少的版本使用.
普通的函數(shù)只需要設(shè)置 xFunc 參數(shù)，而把 xStep 和 xFinal 設(shè)為NULL. 聚合函數(shù)則需要設(shè)置 xStep 和 xFinal 參數(shù)，然后把 xFunc 設(shè)為NULL. 該方法和使用sqlite3_create_aggregate() API一樣.
sqlite3_create_function16()和sqlite_create_function()的不同就在于自定義的函數(shù)名一個(gè)要求是 UTF-16 編碼，而另一個(gè)則要求是 UTF-8.
請(qǐng)注意自定函數(shù)的參數(shù)目前使用了sqlite3_value結(jié)構(gòu)體指針替代了SQLite version 2.X中的字符串指針. 下面的函數(shù)用來(lái)從sqlite3_value結(jié)構(gòu)體中提取數(shù)據(jù):
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*);
long long int sqlite3_value_int64(sqlite3_value*);
const unsigned char *sqlite3_value_text(sqlite3_value*);
const void *sqlite3_value_text16(sqlite3_value*);
int sqlite3_value_type(sqlite3_value*);
上面的函數(shù)調(diào)用以下的API來(lái)獲得上下文內(nèi)容和返回結(jié)果:
void *sqlite3_aggregate_context(sqlite3_context*, int nbyte);
void *sqlite3_user_data(sqlite3_context*);
void sqlite3_result_blob(sqlite3_context*, const void*, int n, void(*)(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);
void sqlite3_result_int(sqlite3_context*, int);
void sqlite3_result_int64(sqlite3_context*, long long int);
void 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*));
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 用戶自定義排序規(guī)則
下面的函數(shù)用來(lái)實(shí)現(xiàn)用戶自定義的排序規(guī)則:
sqlite3_create_collation(sqlite3*, const char *zName, int eTextRep, void*,
int(*xCompare)(void*,int,const void*,int,const void*));
sqlite3_create_collation16(sqlite3*, const void *zName, int eTextRep, void*,
int(*xCompare)(void*,int,const 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() 函數(shù)用來(lái)聲明一個(gè)排序序列和實(shí)現(xiàn)它的比較函數(shù). 比較函數(shù)只能用來(lái)做文本的比較. eTextRep 參數(shù)可以取如下的預(yù)定義值 SQLITE_UTF8, SQLITE_UTF16LE, SQLITE_UTF16BE, SQLITE_ANY，用來(lái)表示比較函數(shù)所處理的文本的編碼方式. 同一個(gè)自定義的排序規(guī)則的同一個(gè)比較函數(shù)可以有 UTF-8, UTF-16LE 和 UTF-16BE 等多個(gè)編碼的版本. sqlite3_create_collation16()和sqlite3_create_collation() 的區(qū)別也僅僅在于排序名稱的編碼是 UTF-16 還是 UTF-8.
可以使用 sqlite3_collation_needed() 函數(shù)來(lái)注冊(cè)一個(gè)回調(diào)函數(shù)，當(dāng)數(shù)據(jù)庫(kù)引擎遇到未知的排序規(guī)則時(shí)會(huì)自動(dòng)調(diào)用該函數(shù). 在回調(diào)函數(shù)中可以查找一個(gè)相似的比較函數(shù)，并激活相應(yīng)的sqlite_3_create_collation()函數(shù). 回調(diào)函數(shù)的第四個(gè)參數(shù)是排序規(guī)則的名稱，同樣sqlite3_collation_needed采用 UTF-8 編碼. sqlite3_collation_need16() 采用 UTF-16 編碼.