[轉]SQLITE3 C語言介面 API 函數簡介

標籤：style   blog   http   color   io   os   ar   使用   sp   

SQLITE3 C語言介面 API 函數簡介

說明:本說明文檔屬作者從接觸 SQLite 開始認識的 API 函數的使用方法, 由本人翻譯, 不斷更新.

/* 2012-05-25 */int sqlite3_open(    const char* filename,    /* 資料庫檔案名, 必須為 UTF-8 格式 */    sqlite3** ppDB            /* 輸出: SQLite 資料庫控制代碼 */);說明:    該函數開啟由 filename 指定的資料庫, 一個資料庫連接控制代碼由 *ppDB 返回(不管是否發生了一個錯誤). 唯一異常是 SQLite 無法為 SQLite 對象分配記憶體空間, 此時將返回 NULL. 如果資料庫被成功開啟(和/或 建立), 函數返回 SQLITE_OK(0). 否則返回一個錯誤碼, 可以通過 sqlite3_errmsg() 取得錯誤原因. 無論是否成功開啟資料庫, 都應該使用 sqlite3_close() 關閉資料庫連接.樣本:    int ret = 0;    char* filename = "./nbsg.db";    sqlite3* pDB = NULL;    to_utf8(filename);    ret = sqlite3_open(filename, &pDB);    if(ret != SQLITE_OK)        ...int sqlite3_close(    sqlite3* pDB    /* 由 sqlite3_open 或基相關的函數開啟的 SQLite 物件控點 */    );說明:    該函數用來析構 sqlite3 對象. 返回 SQLITE_OK 表示對象被成功析構, 以及所有相關的資源被成功回收應用程式必須在關閉之前 "完成(finalize)" 所有的 "先行編譯語句(prepared statements)", 並且關閉所有的 "二進位控制代碼綁定(BLOB handle)", 如果在關閉時還有未完成的先行編譯語句或二進位控制代碼, 那麼函數返回 SQLITE_BUSY(5).樣本:    if(pDB != NULL)    {        sqlite3_close(pDB);        pDB = NULL;    }

/* 2012-05-26 */int sqlite3_errcode(    sqlite3* pDB    /* SQLite3 資料庫控制代碼 */);說明:    該函數返回最近一次調用 sqlite3_ API時產生的錯誤碼.樣本:    int errcode = sqlite3_errcode(pDB);const char *sqlite3_errmsg(    sqlite3* pDB    /* SQLite3 資料庫控制代碼 */);說明:    該函數返回與pDB資料庫指標相關的錯誤資訊, 由英語書寫.    使用者不必考慮記憶體的釋放, 其由SQLite內部管理, 它也將會在下產次調用函數時被覆蓋.樣本:    printf("%s\n", sqlite3_errmsg(pDB));女孩不哭(QQ:191035066)@2012-05-26 11:31:54 @ http://www.cnblogs.com/nbsofer    

/* sqlite3_exec(), 2012-05-28 */int sqlite3_exec(    sqlite3* pDB,        /* sqlite3控制代碼 */    const char* sql,    /* 被執行的 SQL 陳述式 */    int (*callback)(void*,int,char**,char**),  /* 執行/查詢回呼函數 */    void* pvoid,    /* 傳遞給回呼函數的第一個參數 */    char**errmsg    /* 錯誤輸出資訊 */);說明:    該函數用來執行若干條 SQL 陳述式.    該函數包裹了先前版本的 sqlite3_prepare(), sqlte3_step() 和 sqlite3_finalize() 函數, 這樣, 使用者就可以執行簡單的代碼執行多條 SQL 陳述式.    sqlite3_exec()介面執行多條以";"分隔的SQL語句. 如果回呼函數不為 NULL, 則它對每一個行查詢結果都會調用該回呼函數. 如果沒有回呼函數被指定, sqlite3_exec() 只是簡單地忽略查詢結果.    當在執行該SQL語句發生錯誤時, 執行將發生中斷, 並且後面的語句也全部被忽略. 如果 errmsg 參數不為空白任何錯誤資訊將會被寫進由 sqlite3_malloc() 得到的的記憶體空間中, 即 errmsg 指向的記憶體. 為了避免記憶體流失, 應用程式應該在不需要該錯誤資訊後立即調用 sqlite3_free() 釋放該記憶體空間. 如果 errmsg 參數不為 NULL, 並且沒有錯誤發生, errmsg 被設定為 NULL.    如果回呼函數返回非零, sqlite3_exec() 立即中斷查詢, 並且不再執行後續的 SQL 陳述式, 也不再調用回呼函數, sqlite3_exec() 將返回 SQLITE_ABORT 結束執行.樣本:    sqlite3_exec(pDB, to_utf8("delete from tablename where id=123;"), NULL, NULL, NULL);    sqlite3_exec(pDB, to_utf8("create table if not exists tablename (id integer primary key,name text);"), NULL, NULL, NULL);    sqlite3_exec(pDB, to_utf8("insert into tablename (name) values (‘女孩不哭‘);"), NULL, NULL, NULL);    if(sqlite3_exec(pDB, to_utf8("select * from tablename;"), sqlite_callback, NULL, &pszErrMsg) != SQLITE_OK)    {        ...        sqlite3_free(pszErrMsg);        pszErrMsg = NULL;    }
參閱:在 sqlite3 中使用回呼函數(http://www.cnblogs.com/nbsofer/archive/2012/05/29/2523807.html)

/* 2012-05-29, sqlite3_prepare(), sqlite3_step(), sqlite3_finalize() */int sqlite3_prepare(    sqlite3* pDB,            /* 成功開啟的資料庫控制代碼 */    const char* sql,        /* UTF8編碼的 SQL 陳述式 */    int nbytes,                /* 參數 sql 的位元組數, 包含 ‘\0‘ */    sqlite3_stmt** ppStmt,    /* 輸出:先行編譯語句控制代碼 */    const char** pszTail    /* 輸出:指向 sql 語句中未使用的部分 */);說明:    要執行一條 SQL 查詢,其必須先被編譯成位元組碼, 然後才能被其它函數使用.    如果 nbytes 小於零, sql 語句則以第一個 ‘\0‘終結. 如果它非負, 則為讀取的最大長度. 當  nbytes 大於 0 時, 則讀取指定長度, 如果‘\0‘先被讀到, 則以‘\0‘結束. 如果使用者知道被傳入的 sql 語句是以 ‘\0‘ 結尾的, 那麼有一個更好的做法是:把nbytes的值設為該字串的長度(包含‘\0‘), 這樣可以避免 SQLite 複製該字串的一份拷貝, 以提高程式的效率.    如果 pszTail 不為 NULL, 則 *pszTail 指向 sql 中第一個被傳入的 SQL 陳述式的結尾. 該函數只編譯 sql 的第一個語句, 所以 *pszTail 指向的內容則是未被編譯的.    *ppStmt 指向一條可以被 sqlie3_step() 函數使用的先行編譯語句. 如果有錯誤發生, *pszStmt 的值為NULL.    調用者應該使用 sqlite3_finalize() 刪掉被先行編譯的語句.    如果函數成功, 返回 SQLITE_OK, 否則返回一個錯誤碼.int sqlite3_step(    sqlite3_stmt* ppStmt    /* 一條被先行編譯的 sql 語句 */);說明:    當一條語句被 sqlite3_prepare() 或其相關的函數先行編譯後, sqlite3_step() 必須被調用一次或多次來評估該先行編譯語句.    該函數的詳細行為依賴於由 sqlite3_prepare()(或其相關的函數) 產生的是一條怎樣的先行編譯語句.    函數將返回一個以下的結果來標識其執行結果:        SQLITE_BUSY:忙碌. 資料庫引擎無法鎖定資料去完成其工作. 但可以多次嘗試.        SQLITE_DONE:完成. sql 語句已經被成功地執行. 在調用 sqlite_reset() 之前, 當前先行編譯的語句不應該被 sqlite3_step() 再次調用.        SQLITE_ROW:查詢時產生了結果. 此時可以通過相關的"資料訪問函數(column access functions)"來取得資料. sqlite3_step() 的再一次調用將取得下一條查詢結果.        SQLITE_ERROR:發生了錯誤. 此時可以通過 sqlite3_errmmsg() 取得相關的錯誤資訊. sqlite3_step() 不能被再次調用.        SQLITE_MISUSE:不正確的庫的使用. 該函數使用不當.其它:    有關先行編譯的使用, 將在以後的函數介紹中詳細說明.int sqlite3_finalize(    sqlite3_stmt* pStmt    /* 被先行編譯的語句 */);說明:    該函數用來刪除一條被先行編譯的 sql 語句樣本:    sqlite3_finalize(pStmt);    pStmt = NULL;

[轉]SQLITE3 C語言介面 API 函數簡介