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
", 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 的字节数, 包含 ' ' */
sqlite3_stmt** ppStmt, /* 输出:预编译语句句柄 */
const char** pszTail /* 输出:指向 sql 语句中未使用的部分 */
);
说明:
要执行一条 SQL 查询,其必须先被编译成字节码, 然后才能被其它函数使用.
如果 nbytes 小于零, sql 语句则以第一个 '