#define SQLITE_OK 0 /* 成功 */ #define SQLITE_ERROR 1 /* SQL エラーまたはデータベースが見つからない */ #define SQLITE_INTERNAL 2 /* SQLite 内部ロジックエラー */ #define SQLITE_PERM 3 /* アクセス権がない */ #define SQLITE_ABORT 4 /* コールバックルーチンが abort を要求した */ #define SQLITE_BUSY 5 /* データベースファイルがロックされえいる */ #define SQLITE_LOCKED 6 /* データベースのテーブルがロックされている */ #define SQLITE_NOMEM 7 /* malloc() に失敗した */ #define SQLITE_READONLY 8 /* 読み込み専用のデータベースに書き込もうとした */ #define SQLITE_INTERRUPT 9 /* sqlite_interrupt() によって操作が終了させられた */ #define SQLITE_IOERR 10 /* 何らかのディスク I/O エラーが発生した */ #define SQLITE_CORRUPT 11 /* データベースディスクイメージが不正です */ #define SQLITE_NOTFOUND 12 /* (内部専用) テーブルまたはレコードが見つからない */ #define SQLITE_FULL 13 /* データベースが満杯のためデータの挿入ができない */ #define SQLITE_CANTOPEN 14 /* データーベースファイルが開けない */ #define SQLITE_PROTOCOL 15 /* データベースロックプロトコルエラー */ #define SQLITE_EMPTY 16 /* (内部専用) データベーステーブルは空です */ #define SQLITE_SCHEMA 17 /* データベーススキーマが変更された */ #define SQLITE_TOOBIG 18 /* テーブルのひとつの行に対してデータが大きすぎる */ #define SQLITE_CONSTRAINT 19 /* 制約違反のため中止 */ #define SQLITE_MISMATCH 20 /* データ型が合っていない */ #define SQLITE_MISUSE 21 /* ライブラリの使い方が間違っている */ #define SQLITE_NOLFS 22 /* ホストがサポートしていない OS の機能を使った */ #define SQLITE_AUTH 23 /* 権限が無い */ #define SQLITE_ROW 100 /* sqlite_step() は、別の行を準備しています */ #define SQLITE_DONE 101 /* sqlite_step() は、実行を終えた */
多くの SQLite 関数は、成功か失敗を示すために、上記のリストにある整数の結果コードを返します。
void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
集約関数は、ステートを格納するための構造体を割り当てるためにこのルーチンを使います。 このルーチンが特定の集約で初めて呼び出されるとき、大きさ nBytes の新しい構造体が割り当てられ、ゼロクリアされ返されます。 次の呼び出しで（同じ集約インスタンスのために）同じバッファが返されます。 集約の実装は返されたバッファをデータ蓄積のために使うことができます。
割り当てられたバッファは自動的に SQLite が解放します。
int sqlite3_aggregate_count(sqlite3_context*);
この関数は廃止予定です。 この関数は、過去のコードを動かし続けるために当面存在しますが、 新しいコードでは、使わないでください。
この関数を使わせないために、この関数の詳細は説明しません。
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*)); #define SQLITE_STATIC ((void(*)(void *))0) #define SQLITE_TRANSIENT ((void(*)(void *))-1)
sqlite3_prepare() と sqlite3_prepare16() で入力した SQL 文字列において、1つ以上のリテラルを「?」あるいは「:AAA」あるいは「$VVV」パラメーターで置き換えることができます。AAAは英数字の識別子、VVV は TCL プログラム言語の文法に従った変数名です。. （「ホストパラメータ名」と呼ばれる）これらのパラメータの値は sqlite3_bind_*() ルーチンを使って割り当ることができます。
sqlite3_bind_*() ルーチンの最初の引数は常に sqlite3_prepare() が返す sqlite3_stmt 構造体へのポインタです。 2番目の引数はセットするパラメータのインデックスです。 最初のパラメータのインデックス値は 1 です。 同じ名前を持つパラメータが何度も使われる場合、2回目以降に出現するときは最初に出現したときと同じインデックスを持っています。 望むなら、名前付きパラメータのインデックスを sqlite3_bind_parameter_name() API を使って検索することができます。
3番目の引数はパラメータに結合する値です。
4番目の引数を持つルーチンは、その値はパラメータのバイト数です。 明確に記すと、値は、文字の数ではなく文字列のバイト数です。 バイト数には、文字列の最後のゼロ終端を含みません。 4番目のパラメータが負の場合、文字列の長さは最初のゼロ終端までのバイト数です。
sqlite3_bind_blob() 、 sqlite3_bind_text() 、sqlite3_bind_text16() の5番目の引数は、 SQLite がこの関数の処理を終えた後、 BLOB あるいはテキストを削除するために使うデストラクタです。 5番目の引数が特別な値 SQLITE_STATIC の場合、ライブラリは情報が静的でアンマネージな空間にあると想定し、解放する必要もありません。 5番目の引数が値 SQLITE_TRANSIENT を持つ場合、リターンする前にSQLite は自分用にデータのプライベートなコピーを作ります。
sqlite3_bind_*() ルーチンは、 sqlite3_prepare() あるいは sqlite3_reset() の後に、そして sqlite3_step() の前に呼び出さなくてはなりません。 結合は、 sqlite3_reset() ルーチンでクリアされません。 結合されていないパラメータは NULL と解釈されます。
これらのルーチンは、成功すると SQLITE_OK を、何かがうまくいかないならエラーコードを返します。パラメータインデックスが範囲を超えている場合、 SQLITE_RANGE を返します。 malloc が失敗した場合、 SQLITE_NOMEM を返します。 これらのルーチンを間違った状態、あるいはすでに完了した仮想マシンで呼び出した場合、 SQLITE_MISUSE を返します。
int sqlite3_bind_parameter_count(sqlite3_stmt*);
引数として与えられたコンパイル済みステートメントのパラメータの数を返します。
int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
引数として与えられた名前を持つパラメータのインデックスを返します。 名前は正確に一致しなければなりません。 引数として与えられた名前を持つパラメータがない場合、0を返します。 文字列 zName は常に UTF-8エンコーディングです。
const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int n);
ンパイル済みステートメントの n 番目のパラメータ名を返します。 「:AAA」あるいは「$VVV」という形式のパラメータは、「:AAA」あるいは「$VVV」という文字列の名前を持ちます。 別の言い方をすると、最初の":" あるいは '$' は、名前の一部に含まれます。 「?」という形式のパラメータは、名前を持ちません。
値 n が範囲外、あるいは n 番目のパラメータに名前が無い場合、 NULL を返します。 返される文字列は、常に UTF-8 エンコードです。
int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
この関数によって、他のスレッドやプロセスがロック中のデータベーステーブルを 開こうとしたとき常に呼び出されるコールバック関数を指定します。 busy callback が NULL だった場合、ロックに遭遇した時点で即座に SQLITE_BUSY を返します。 busy callback が NULL 以外の場合、コールバックは2つの引数を伴って呼び出されます。 2番目の引数は、同じロック中に busy callback が既に呼び出されている回数です。 busy callback が 0 を返す場合、それ以上のデータベースへのアクセスは拒否され、 SQLITE_BUSY が返されます。 コールバック関数が 0 以外を返す場合、後続の要求によって読み込み用に データベースが開かれます。 そして、このサイクルが繰り返されます。
ロック競合がある場合には、busy ハンドラが存在したとしても、 それが呼び出されることは保証されません。 SQLite が busy ハンドラを呼び出すことはデッドロックに繋がると検知した場合、 ハンドラを呼び出さずに SQLITE_BUSY を返します。 あるプロセスがリザーブロックに移行させようとしている読み取りロックを持ち、 2番目のプロセスが排他的ロックに移行させようとしているリザーブロックを持つ 状況を考慮してください。 最初のプロセスは、2番目のプロセスに阻止されるため続行できません。 そして、 2番目のプロセスは最初のプロセスに阻止されるため続行できません。 もしも両方のプロセスが busy ハンドラを呼び出したなら、いずれも進むことが出来ないでしょう。 そこで SQLite は、最初のプロセスによる読み込みロックの解放が起こり2番目のプロセスが 続行することを期待して、最初のプロセスには SQLITE_BUSY を返します。
デフォルトの busy コールバック は NULL です。
SQLite は再入可能ですから、busy ハンドラは新規にクエリーを開始できます。 （いつどこで誰がそんなことをするのかは知りませんが、理屈の上では可能です。） しかし、busy ハンドラはデータベースを閉じてはいけません。 busy ハンドラ内からデータベースを閉じると実行中の問い合わせの元からデータ構造体を はぎとってしまいます。 そしておそらくはコアダンプを引き起こすでしょう。
int sqlite3_busy_timeout(sqlite3*, int ms);
このルーチンは、テーブルがロックされている時しばらく休眠する busy ハンドラを セットします。 ハンドラは、少なくとも"ms"ミリ秒休眠するまでは何度でも休眠します。 "ms"ミリ秒休眠した後、ハンドラは 0 を返します。 これによって、 sqlite3_exec() が SQLITE_BUSY を返す結果となります。
ゼロかゼロ以下の引数でこのルーチンを呼び出すと、すべての busy ハンドラが 切り離されます。
int sqlite3_changes(sqlite3*);
この関数は、最後に完了したINSERT、UPDATE、DELETE ステートメントによって変更 （または、挿入、消去）されたデーターベースの行の数を返します。 直接 INSERT、UPDATE、DELETE ステートメントによって指定された変更のみ数えられます。 トリガーによって引き起こされた間接的な変更は数えられません。 トリガーによって引き起こされる変更を含むすべての変更の数を見るには、 sqlite3_total_changes() を使ってください。
トリガー本体の中で、sqlite3_changes()関数はトリガー本体内で一番最後に完了した INSERT、UPDATE、DELETE ステートメントで変更された行の数を報告するために動作します。
SQLite は、WHERE 句の無い "DELETE FROM table" コマンドをテーブルを一度ドロップした のち再作成するように実装しています。 （この方法はテーブルから個別の要素を削除するよりずっと速く、たいへんうまくいっています。） この最適化のために、"DELETE FROM table" に対する変更の計数は当初テーブルにあった 要素の数にかかわらずゼロになります。 消去された行の正確な数を計数するためには、代わりに "DELETE FROM table WHERE 1" を 使ってください。
int sqlite3_clear_bindings(sqlite3_stmt*);
コンパイル済み SQL ステートメントのすべてのパラメータを NULL にセットしなおします。
int sqlite3_close(sqlite3*);
以前に sqlite3_open() または sqlite3_open16() から返された構造体へのポインタと共に この関数を呼び出すとデーターベースは閉じます。 閉じることに成功した場合、SQLITE_OK を返します。
削除していない構築済みステートメントがある場合、 SQLITE_BUSY を返します。 引数が sqlite3_open() によって返される有効な接続ポインタで無い場合、 あるいは接続ポインタがすでに閉じられていたなら、SQLITE_ERROR を返すでしょう。
int sqlite3_collation_needed( sqlite3*, void*, void(*)(void*,sqlite3*,int eTextRep,const char*) ); int sqlite3_collation_needed16( sqlite3*, void*, void(*)(void*,sqlite3*,int eTextRep,const void*) );
データベースを使用する前にすべての照合シーケンスを登録しなければならなくなることを 避けるため、未定義の照合シーケンスが必要とされた時に呼び出される単一のコールバック関数を データベースハンドルとともに登録しておくことができます。
関数が、sqlite3_collation_needed() API を使って 登録された場合、未定義の照合シーケンスの名前は UTF-8 でコード化された文字列として 渡されます。 sqlite3_collation_needed16() を使った場合は、マシンネイティブのバイトオーダーで UTF-16 として名前が渡されます。 いずれかの関数を呼び出すと、既存のすべての関数を置き換えます。
ユーザー関数が呼び出されたとき、渡される最初の引数は sqlite3_collation_needed() または sqlite3_collation_needed16() の2番目の引数のコピーです。 2番目の引数はデータベースハンドルです。 3番目の引数は、必要とする照合シーケンス関数の最適な形式を示す SQLITE_UTF8、 SQLITE_UTF16BE または SQLITE_UTF16LE のどれか一つです。 4番目の引数は、必要とする照合シーケンスの名前です。
照合シーケンスは、すでに説明した sqlite3_create_collation() または sqlite3_create_collation16() API を使って collation-needed コールバックによって SQLite へ返されます。
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); long long int sqlite3_column_int64(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); #define SQLITE_INTEGER 1 #define SQLITE_FLOAT 2 #define SQLITE_TEXT 3 #define SQLITE_BLOB 4 #define SQLITE_NULL 5
これらのルーチンは現在のクエリーの結果行の一つのカラムについての情報を返します。 どの場合も最初の引数は実行中の SQL ステートメントへのポインタ（sqlite3_prepare()
から返された sqlite_stmt*）です。 2番目の引数は、情報を返してほしいカラムのインデックスです。
iCol は、ゼロから始まるインデックスです。 一番左のカラムは0のインデックスを持っています。
SQL ステートメントが正当な行を指していない場合、および、カラムインデックスが範囲外の場合、結果は未定義です。
結果が BLOB の場合、 sqlite3_column_bytes() ルーチンはその BLOB のバイト数を返します。 型変換は起こりません。結果が文字列（あるいは文字列に変換できる数）の場合、 sqlite3_column_bytes() は値を UTF-8 文字列に変換し、結果文字列のバイト数を返します。 戻り値は、文字列の終わりの \000 終端を含みません。 sqlite3_column_bytes16() ルーチンは値を UTF-16 エンコードに変換し、結果文字列の（文字数ではなく）バイト数を返します。 \u0000 終端は、この計算に含みません。
妥当な場合、これらのルーチンは値の変換を試します。 例えば、内部表現が FLOAT のときにテキストの結果が要求された場合、自動変換のために sprintf () が内部で使われます。 次の表は、適用される変換の説明です。
Internal Type Requested Type Conversion NULL INTEGER Result is 0 NULL FLOAT Result is 0.0 NULL TEXT Result is NULL pointer NULL BLOB Result is NULL pointer INTEGER FLOAT Convert from integer to float INTEGER TEXT ASCII rendering of the integer INTEGER BLOB Same as for INTEGER->TEXT FLOAT INTEGER Convert from float to integer FLOAT TEXT ASCII rendering of the float FLOAT BLOB Same as FLOAT->TEXT TEXT INTEGER Use atoi() TEXT FLOAT Use atof() TEXT BLOB No change BLOB INTEGER Convert to TEXT then use atoi() BLOB FLOAT Convert to TEXT then use atof() BLOB TEXT Add a \000 terminator if needed
int sqlite3_column_count(sqlite3_stmt *pStmt);
prepared SQL ステートメントによって返された結果セットのカラムの数を返します。 pStmt がデータを返さない SQL ステートメント（例えばUPDATE）の場合、 このルーチンは０を返します。
sqlite3_data_count() を参照してください。
const char *sqlite3_column_database_name(sqlite3_stmt *pStmt, int N); const void *sqlite3_column_database_name16(sqlite3_stmt *pStmt, int N);
ステートメント pStmt によって返される N 番目のカラムがカラムのリファレンスであれば、 カラムを含んでいるデータベースの名前（"main"、"temp"のどちらかまたは接続された データベースの名前）にアクセスするためにこれらの関数が使えます。 N 番目のカラムがカラムのリファレンスではなかった場合、NULL が返ります。
どの式がカラムのリファレンスとみなされるかについて正確な説明を sqlite3_column_decltype() の記述で見てください。
関数 sqlite3_column_database_name() は、 UTF-8 で符号化された文字列へのポインタを返します。 sqlite3_column_database_name16() は、UTF-16 で符号化された文字列を返します。
const char *sqlite3_column_decltype(sqlite3_stmt *, int i); const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
最初の引数は、構築済み SQL ステートメントです。 このステートメントが SELECT ステートメントで、返された SELECT の結果セットの N 番目のカラムがテーブルカラムの場合、テーブルカラムの宣言型が返されます。 結果セットの N 番目のカラムがテーブルカラムではない場合、NULL ポインターが返ります。 返される文字列は、sqlite3_column_decltype() では UTF-8 で符号化され、sqlite3_column_decltype16() では UTF-16 です。 例として以下のデータベーススキーマを使います。
CREATE TABLE t1(c1 INTEGER);
そして以下のステートメントをコンパイルします。
SELECT c1 + 1, c1 FROM t1;
このルーチンは、2番目の結果カラム (i==1) に対して文字列 "INTEGER" を返し、 最初の結果カラム (i==0) に対して NULL を返すでしょう。
以下のステートメントをコンパイルすると、このルーチンは最初の結果カラムに対して "INTEGER" を返すでしょう。
SELECT (SELECT c1) FROM t1; SELECT (SELECT c1 FROM t1); SELECT c1 FROM (SELECT c1 FROM t1); SELECT * FROM (SELECT c1 FROM t1); SELECT * FROM (SELECT * FROM t1);
const char *sqlite3_column_name(sqlite3_stmt*,int); const void *sqlite3_column_name16(sqlite3_stmt*,int);
最初の引数は構築済みSQLステートメントです。 この関数は、N番目のカラムの名前を返します。 Nは関数の2番目の引数です。 返される文字列は、 sqlite3_column_name() では UTF-8 で、 sqlite3_column_name16() では UTF-16 です。
const char *sqlite3_column_origin_name(sqlite3_stmt *pStmt, int N); const void *sqlite3_column_origin_name16(sqlite3_stmt *pStmt, int N);
ステートメント pStmt によって返される N 番目のカラムがカラムのリファレンスである場合、 これらの関数は、データベーススキーマ内の参照されるカラムのスキーマ名にアクセスするために 使えます。 N 番目のカラムがカラムのリファレンスではない場合、NULL が返ります。
どの式がカラムのリファレンスとみなされるかについて正確な説明を sqlite3_column_decltype() の記述で見てください。
関数 sqlite3_column_origin_name() は UTF-8 で 符号化された文字列を返し、sqlite3_column_origin_name16() は UTF-16 で符号化された 文字列を返します。
const char *sqlite3_column_table_name(sqlite3_stmt *pStmt, int N); const void *sqlite3_column_table_name16(sqlite3_stmt *pStmt, int N);
ステートメント pStmt によって返される N 番目のカラムがカラムのリファレンスの場合、 これらの関数は、カラムを含む表の名前にアクセスするために使えます。 N 番目のカラムがカラムの参照でない場合、NULL が返ります。
どの式がカラムのリファレンスとみなされるかについて正確な説明を sqlite3_column_decltype() の記述で見てください。
関数 sqlite3_column_table_name() は UTF-8 で 符号化された文字列を返し、sqlite3_column_table_name16() は UTF-16 で符号化された 文字列を返します。
void *sqlite3_commit_hook(sqlite3*, int(*xCallback)(void*), void *pArg);
Experimental
Register a callback function to be invoked whenever a new transaction is committed. The pArg argument is passed through to the callback. callback. If the callback function returns non-zero, then the commit is converted into a rollback.
If another function was previously registered, its pArg value is returned. Otherwise NULL is returned.
Registering a NULL function disables the callback. Only a single commit hook callback can be registered at a time.
int sqlite3_complete(const char *sql); int sqlite3_complete16(const void *sql);
これらの関数は、与えられた文字列が1つ以上の完全なSQLステートメントを構成する場合、 trueを返します。 引数は、sqlite3_complete() では NULL で終わる UTF-8 文字列、 sqlite3_complete16() では NULL で終わる UTF-16 文字列で なければなりません。
int sqlite3_create_collation( sqlite3*, const char *zName, int pref16, void*, int(*xCompare)(void*,int,const void*,int,const void*) ); int sqlite3_create_collation16( sqlite3*, const char *zName, int pref16, void*, int(*xCompare)(void*,int,const void*,int,const void*) ); #define SQLITE_UTF8 1 #define SQLITE_UTF16BE 2 #define SQLITE_UTF16LE 3 #define SQLITE_UTF16 4
これら2つの関数は、最初の引数として指定する sqlite3 ハンドルへ新しい照合シーケンスを 追加するために使います。
新しい照合シーケンスの名前は、 sqlite3_create_collation() では UTF-8 文字列 として、sqlite3_create_collation16() では UTF-16 で指定します。 両方のケースで名前は関数の2番目の引数として渡されます。
3番目の引数は、ユーザーが提供するルーチンが、UTF-8、UTF-16 リトルエンディアン、 UTF-16 ビッグエンディアンのうちどれを使って符号化された文字列が渡されることを 期待するか示す定数 SQLITE_UTF8、SQLITE_UTF16LE または SQLITE_UTF16BE のうち どれか一つでなければなりません。 SQLITE_UTF16 定数は、テキスト文字列としてホストマシンのネイティブバイトオーダーによる UTF-16 を期待することを示します。
ユーザーが供給するルーチンへのポインタが5番目の引数として渡されなければなりません。 もしそれが NULL である場合、（もうそれ以上 SQLite がそれを呼び出すことが出来ないように） 照合シーケンスを削除することと同じことです。 ユーザーが供給する関数が呼び出されるたびに、 sqlite3_create_collation() または sqlite3_create_collation16() で4番目の引数として渡された void* のコピーを最初の 引数として渡します。
ユーザー提供ルーチンの残りの引数は、それぞれ [length, data] のペアと照合シーケンスが 登録されたときに3番目の引数として渡されたエンコーディングの符号化によって表現される 2つの文字列です。 ユーザールーチンは、最初の文字列が2番目の文字列より小さいか、イコールか、または 大きいかによって負、ゼロ、または正を返さなければなりません。 たとえば、(STRING1 - STRING2)。
int sqlite3_create_function( sqlite3 *, const char *zFunctionName, int nArg, int eTextRep, void *pUserData, 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 *pUserData, 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
これら2つの関数は、C言語で実装されたSQL 関数または集約関数を追加するために使います。 これら2つのルーチンの間の違いは、（スカラー）関数または集約関数の名前である2番目の引数が sqlite3_create_function() では UTF-8 で、 sqlite3_create_function16() では UTF-16 でコード化されるということのみです。
最初の引数は、新しい関数または集約関数を追加するデータベースのハンドルです。 1つのプログラムが内部で1つ以上のデータベースハンドルを使う場合、ユーザー関数または 集約関数は、個別にそれらが使われるそれぞれのデータベースハンドルに追加しなくてはなりません。
3番目の引数は、関数または集約関数がとる引数の数です。 この引数が -1 の場合、関数または集約関数がどんな数の引数でも取るということです。
4番目の引数 eTextRep で、この関数がどの形式のテキスト引数を望むか指定します。 どの関数も UTF-8、UTF-16le、UTF-16be で動作できるようにするべきです。 しかし、いくつかの実装では、ある表現が他のものよりもより効率的である場合があります。 ユーザーは、引数のテキスト表現に依存して呼び出される別個の実装を同一の関数に 規定することができます。 最もよくマッチする実装が使われます。 どんなテキスト表現が使われても構わない唯一の実装のみある場合、 4番目の引数を SQLITE_ANY にするべきです。
5番目の引数は任意のポインタです。 関数の実装は、sqlite_user_data() API を使ってこのポインタへアクセスすることができます。
6番目、7番目、8番目の、xFunc、xStep、xFinal は、ユーザーが実装したユーザー関数 または集約関数の C 言語関数へのポインタです。 スカラー関数は、 xFunc コールバックの実装のみを必要とします。 xStep と xFinal 引数として NULL を渡すべきです。 集約関数は、xStep と xFinal の実装を必要とします。 xFunc として NULL を渡すべきです。 既存のユーザー関数または集約関数を消去するには、3つすべての関数コールバックとして NULL を渡します。 xFunc と xFinal または、xStep があるのに xFinal が無いといったようなおかしな コールバックの組み合わせを指定すると SQLITE_ERROR が返ります。
int sqlite3_data_count(sqlite3_stmt *pStmt);
結果セットの現在行における値の数を返します。
SQLITE_ROW を返す sqlite3_step() 呼び出しの後では、 このルーチンは、 sqlite3_column_count() 関数と 同じ値を返します。 sqlite3_step() が SQLITE_DONE、SQLITE_BUSY またはエラーコードを返した後、あるいは、構築済みステートメントを使って sqlite3_step() を呼び出す前なら、 このルーチンはゼロを返します。
int sqlite3_db_handle(sqlite3_stmt*);
引数で与えられた構築済みステートメントが帰属する sqlite* データベースハンドルを返します。 これは、最初にステートメントを作成するために使った sqlite3_prepare() の第1引数と同じデータベースハンドルです。
int sqlite3_enable_shared_cache(int);
このルーチンは、同じデータベースへの接続間におけるデータベースキャッシュと スキーマデータ構造体の共有の有効化または無効化を行います。 引数で true を指定すると共有が有効化し、false を指定すると無効化します。
キャッシュの共有はスレッドバイスレッドの原則の上に有効化と無効化を行います。 このルーチンのそれぞれの呼び出しは、このルーチンが呼び出されたのと同じスレッドで 作成された接続についてのみキャッシュの共有を有効化または無効化させます。 異なるスレッド上で実行中のデータベース接続間でキャッシュを共有する機構はありません。
スレッドをシャットダウンする前に共有を無効化しなくてはなりません。 そうしなければスレッドはメモリーリークを引き起こすでしょう。 共有を無効化するために 0 を引数にこのルーチンを呼び出してください。 あるいは、sqlite3_thread_cleanup() API を使ってください。
現在のスレッドでアクティブなデータベース接続があるとき、 このルーチンを呼び出してはいけません。 アクティブなデータベース接続がある間にキャッシュの共有を有効化または無効化させると メモリーの汚染が引き起こされるでしょう。
共有キャッシュが有効化している間、以下のルーチンは常に同じスレッドから呼び出さなくてはなりません。 sqlite3_open()、 sqlite3_prepare()、 sqlite3_step()、 sqlite3_reset()、 sqlite3_finalize()、 sqlite3_close()。 これは、他の接続との共有が可能なように、共有キャッシュがスレッド固有のストレージを 利用するという事実の結果です。
このルーチンは、共有キャッシュの有効化または無効化が成功した場合、SQLITE_OK を返し、 その他の場合エラーコードを返します。
共有キャッシュは後方互換性のために規定値では無効化されています。
int sqlite3_errcode(sqlite3 *db);
sqlite3 ハンドル「db」と結びつく一番最後に失敗した sqlite3_* API 呼び出しの エラーコードを返します。 優先される API 呼び出しが失敗し、しかし一番最後の API 呼び出しが成功した場合、このルーチンからの戻り値は未定義です。
多くの sqlite3_* 関数の呼び出しはエラーコードを設定し、そしてsqlite3_errcode() 、 sqlite3_errmsg() と sqlite3_errmsg16() が文字列を返します。 （以前の値は上書きされます。） sqlite3_errcode() 、sqlite3_errmsg()、sqlite3_errmsg16() の呼び出しは、 エラーコードを設定しないことに注意してください。 エラーコードを返さない API ルーチン（たとえば sqlite3_data_count() 、sqlite3_mprintf()） を呼び出すことで、この関数が返すエラーコードが変更されることはありません。
他のどのような sqlite3_* API 呼び出しもこの間に起こらないと仮定するなら、 この関数が返すエラーコードは sqlite3_errmsg()、sqlite3_errmsg16() が返す文字列と 同じエラーと結び付いています。
const char *sqlite3_errmsg(sqlite3*); const void *sqlite3_errmsg16(sqlite3*);
最後の sqlite3_* API 呼び出しのエラー状態を英語で説明した UTF-8 符号化文字列 （sqlite3_errmsg）あるいは UTF-16 符号化文字列（sqlite3_errmsg16）のポインタを返します。 返された文字列は常に 0x00 バイトで終わります。
最後の API 呼び出しが成功していた場合、文字列「not an error」を返します。
１つ以上のSQL ステートメントを実行する関数。int sqlite3_exec( sqlite3*, /* An open database */ const char *sql, /* SQL to be executed */ sqlite_callback, /* Callback function */ void *, /* 1st argument to callback function */ char **errmsg /* Error msg written here */ );
SQL ステートメントの１つ以上が問合せの場合、3番目の引数で指定されたコールバック関数が問合せ結果のそれぞれの行に対して一度ずつ実行されます。 このコールバックは通常 0 を返すべきです。 コールバックがゼロ以外の値を返す場合、問合せは中止され、後の SQL ステートメントすべてがスキップされます、そして sqlite3_exec() 関数は SQLITE_ABORT を返します。
4 番目の引数はコールバック関数に最初の引数として渡される任意のポインタです。
コールバック関数の２番目の引数は問合せ結果のカラムの数です。 コールバックの３番目の引数はそれぞれのカラムのための値を持つ文字列の配列です。 コールバックへの４番目の引数はそれぞれのカラムの名前を持つ文字列の配列です。
コールバック関数は、問合せに関してさえNULL であるかもしれません。 NULL コールバックはエラーではありません。 それは単にコールバックが呼び出されないであろうことを意味します。
SQL を解析するか、あるいは評価している間に（ただし、コールバックを実行している間にではなく）エラーが発生した場合、適切なエラーメッセージが malloc () から得られたメモリに書き込まれ、*errmsg がそのメッセージを指します。 呼出し側はエラーメッセージを持つメモリを解放することに責任があります。 そのために sqlite3_free() を使ってください。 errmsg == NULL のとき、エラーメッセージが書かれることはありません。
エラーがない場合、戻り値は SQLITE_OK です。エラーがある場合は、他のリターンコードです。 特定の戻り値はエラータイプに依存します。
データベースファイルがロックされているか使用中で問合せが実行出来ない場合、 この関数は SQLITE_BUSY を返します。 （この動作は、 sqlite3_busy_handler() や sqlite3_busy_timeout() 関数を使っていくらか修正できます。）
int sqlite3_expired(sqlite3_stmt*);
引数として供給されるステートメントが再コンパイルを必要としている場合、 （ゼロ以外の）TRUE を返します。 sqlite3_prepare() がプログラムを生成してから 実行環境が変更された場合は常に、ステートメントの再コンパイルが必要になります。 例をあげると、新しい関数や照合順序が追加されたり、 authorizer 関数が追加されたり変更された場合です。
int sqlite3_finalize(sqlite3_stmt *pStmt);
sqlite3_finalize() 関数は、以前に sqlite3_prepare() あるいは sqlite3_prepare16() を 呼び出して得た構築済み SQL ステートメントを削除するために呼び出します。 ステートメントが正常に実行されていたか、あるいはまったく実行されていなかった場合、 SQLITE_OK を返します。 ステートメントの実行に失敗していた場合、エラーコードを返します。
すべての構築済みステートメントは、sqlite3_close() を呼ぶ前に、 あるいは SQLITE_BUSY の戻り値で失敗して閉じる時に削除しなくてはいけません。
このルーチンは仮想マシンの実行中いかなる時点でも呼び出すことができます。 このルーチンを呼び出したとき仮想マシンが実行を完了しないなら、 それはエラーあるいは割り込みに遭遇していると思われます。 （sqlite3_interrupt() を見てください。） 不完全な更新は巻きもどされるでしょう。 そして、状況によってはトランザクションが取り消されます。 そして戻り値として SQLITE_ABORT を返します。
void sqlite3_free(char *z);
このルーチンは、 sqlite3_mprintf() や sqlite3_vmprintf() で確保されたメモリーを解放するために使います。
int sqlite3_get_table( sqlite3*, /* An open database */ const char *sql, /* SQL to be executed */ char ***resultp, /* Result written to a char *[] that this points to */ int *nrow, /* Number of result rows written here */ int *ncolumn, /* Number of result columns written here */ char **errmsg /* Error msg written here */ ); void sqlite3_free_table(char **result);
このルーチンは、sqlite3_exec() の単なるラッパーにすぎません。 結果行それぞれのためにユーザーが提供するコールバックを呼び出す代わりに、 このルーチンは、malloc() で確保したメモリーへ結果行それぞれを記録し、 問い合わせの終了後、すべての結果を返します。
例として、このようなテーブルの問い合わせ結果を考えてみてください。
Name | Age
-----------------------
Alice | 43
Bob | 28
Cindy | 21
3番目の引数が &azResult の場合、関数が返った後 azResult は以下のデータを 含むでしょう。
azResult[0] = "Name";
azResult[1] = "Age";
azResult[2] = "Alice";
azResult[3] = "43";
azResult[4] = "Bob";
azResult[5] = "28";
azResult[6] = "Cindy";
azResult[7] = "21";
カラムヘッダを持つデータの付加行があることに注目してください。 しかし、*nrow が返す値は 3 にとどまります。 *ncolumn は、2 がセットされます。 一般に、azResult に挿入される値の数は ((*nrow) + 1)*(*ncolumn) です。
関数呼び出しの結果を使い終わった後、malloc したメモリーを解放するために sqlite3_free_table() へ結果データのポインタを渡すべきです。 malloc() を起こす方法が複数あるため、呼び出し側が直接 malloc() を呼んではいけません。 sqlite3_free_table() のみが、適切かつ安全にメモリーを解放できます。
このルーチンの戻り値は、sqlite3_exec() と同じです。
int sqlite3_get_autocommit(sqlite3*);
データベース接続が autocommit モードであるかどうか見るためにテストします。 そうである場合 TRUE を、そうでない場合 FALSE を返します。 autocommit モードは、デフォルトでオンです。 autocommit は BEGIN ステートメントで停止され、次の COMMIT または ROLLBACK で 再び使用可能になります。
int sqlite3_global_recover();
この関数は out-of-memory エラーからの回復に関連して使用するものでした。 しかし、SQLite version 3.3.0 の時点で out-of-memory の回復は自動化されており、 現在ではこのルーチンは何もしません。 このルーチンは昔のコードでのリンクエラーを避けるために維持されています。
void sqlite3_interrupt(sqlite3*);
この関数は、どんな処理中のデータベース操作でも最も早い機会に中断させリターンさせます。 このルーチンは、一般に、ユーザーが長い問合せ操作をすぐに停止させようと「取り消し」や Ctrl-C を押したときに呼び出します。
long long int sqlite3_last_insert_rowid(sqlite3*);
SQLite テーブルの各要素はユニークな整数キーを持っています。 （INTEGER PRIMARY KEY を持つならキーはその値です。 そうでなければキーはランダムに生成されます。 ユニークキーはいつでもカラムの ROWID、OID、_ROWID_ として利用できます。） このルーチンは、データベースで最後に insert された整数キーを返します。
この関数は、MySQL の mysql_insert_id() と類似しています。
const char *sqlite3_libversion(void);
ライブラリのバージョン番号を含む文字列へのポインタを返します。 同じ文字列が、"sqlite3_version" という名前のグローバル変数で利用できます。 Windowsでは、DLL 内のグローバル変数にアクセスできないためこのインターフェースが提供されます。
char *sqlite3_mprintf(const char*,...); char *sqlite3_vmprintf(const char*, va_list);
これらのルーチンは、標準 C ライブラリの "sprintf()" の変形です。 決してバッファオーバーフローを引き起こすことが無いように結果文字列は malloc() で確保した メモリーに書き込まれます。 これらのルーチンは同様に SQL ステートメントの構築に役立つ追加のフォーマットオプションを いくらか実装しています。
これらのルーチンが返した文字列は sqlite3_free() の呼び出しによって解放しなければなりません。
通常の printf フォーマットオプションのすべてが適用されます。 加えて "%q" オプションがあります。 %q は、引数リストから null 終端文字列を置き換えするという点で %s と同様に作用します。 しかし、 %q はすべての '\'' 文字を二重化します。 %q は、文字列リテラル内で使用するために設計されています。 '\'' 文字をそれぞれ二重化することによってエスケープを行い、 文字列に挿入できるようにします。
たとえば、いくつかの文字列変数が以下のようなテキストを含むとします。
char *zText = "It's a happy day!";
以下のように SQL ステートメント内でこのテキストを使うことができます。
sqlite3_exec_printf(db, "INSERT INTO table VALUES('%q')",
callback1, 0, 0, zText);
%q フォーマット文字列が使われるため、 zText 内の '\'' 文字はエスケープされ 以下のような SQL が生成されます。
INSERT INTO table1 VALUES('It''s a happy day!')
これは妥当といえます。 もしも、%q の代わりに %s を使っていたなら生成された SQL は このように見えていたはずです。
INSERT INTO table1 VALUES('It's a happy day!');
この2つ目の例は SQL 構文エラーです。 一般的な原則として、テキストを文字列リテラルに挿入するとき常に %s の代わりに %q を使うべきです。
int sqlite3_open( const char *filename, /* Database filename (UTF-8) */ sqlite3 **ppDb /* OUT: SQLite db handle */ ); int sqlite3_open16( const void *filename, /* Database filename (UTF-16) */ sqlite3 **ppDb /* OUT: SQLite db handle */ );
「filename」は、 sqlite3_open() では UTF-8 エンコード、 sqlite3_open16() ではネイティブバイトオーダーのUTF-16 コードです。 エラーが発生しても、 sqlite3* ハンドルを* ppDb で返します。 データベースのオープンが成功したら（あるいは作成されたら）SQLITE_OK を返します。それ以外の場合は、エラーコードを返します。 sqlite3_errmsg() あるいは sqlite3_errmsg16() ルーチンがエラーの英語による説明を得るために使えます。
データベースファイルが存在しない場合、新しいデータベースが作成されるでしょう。 sqlite3_open() が呼ばれた場合、データベースのためのエンコーディングは UTF-8 でしょう、sqlite3_open16 が使われるならUTF-16 です。
データベースを開いたときエラーが発生したか否かにかかわらず、必要なくなった時点で、sqlite3* ハンドルをsqlite3_close() に渡すことで結び付いたリソースを解放するべきです。
返された sqlite3* は、それが作られた同じスレッドでのみ使うことができます。 あるスレッドで sqlite3_open() を呼び出した結果のデータベースハンドルを、別のスレッドで使うために渡すことは間違いです。 この制限は、いくつかのスレッド実装のファイルロックと相互作用する風変わりな仕様策定（バグ？）の結果です。
int sqlite3_prepare( sqlite3 *db, /* Database handle */ const char *zSql, /* SQL statement, UTF-8 encoded */ int nBytes, /* Length of zSql in bytes. */ sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const char **pzTail /* OUT: Pointer to unused portion of zSql */ ); int sqlite3_prepare16( sqlite3 *db, /* Database handle */ const void *zSql, /* SQL statement, UTF-16 encoded */ int nBytes, /* Length of zSql in bytes. */ sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const void **pzTail /* OUT: Pointer to unused portion of zSql */ );
最初の引数「db」は SQLite データベースハンドルです。 2 番目の引数「 zSql 」は、 UTF-8 あるいは UTF-16 （上記参照）コードのコンパイルされるステートメントです。 次の引数「 nBytes 」がゼロより小さい場合、 zSql が最初の nul 終端まで読まれます。 「nBytes」がゼロより大きい場合、「nBytes」は、文字列 zSql の（文字ではなく）バイト単位の長さです。
*pzTail は、 zSql の最初の SQL ステートメント終端の次のバイトを指し示します。 このルーチンは zSql の最初のステートメントをコンパイルするだけです。 そして*pzTail は、何がコンパイルされていないかを示す状態になります。
*ppStmt は、 sqlite3_step() を使って実行することができるコンパイル済み SQL ステートメントを指し示している状態になります。 エラーがあった場合、 *ppStmt に NULL がセットされるでしょう。 入力テキストが SQL を含まない（入力が空の文字列やコメント）場合、 * ppStmt に NULL がセットされます。 使い終わった後、呼出し側は sqlite3_finalize() を使ってこのコンパイル済み SQL ステートメントを削除する責任があります。
成功の場合、 SQLITE_OK が返されます。 その他の場合エラーコードが返されます。
void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
Experimental
This routine configures a callback function - the progress callback - that is invoked periodically during long running calls to sqlite3_exec(), sqlite3_step() and sqlite3_get_table(). An example use for this API is to keep a GUI updated during a large query.
The progress callback is invoked once for every N virtual machine opcodes, where N is the second argument to this function. The progress callback itself is identified by the third argument to this function. The fourth argument to this function is a void pointer passed to the progress callback function each time it is invoked.
If a call to sqlite3_exec(), sqlite3_step() or sqlite3_get_table() results in less than N opcodes being executed, then the progress callback is not invoked.
To remove the progress callback altogether, pass NULL as the third argument to this function.
If the progress callback returns a result other than 0, then the current query is immediately terminated and any database changes rolled back. If the query was part of a larger transaction, then the transaction is not rolled back and remains active. The sqlite3_exec() call returns SQLITE_ABORT.
int sqlite3_release_memory(int N);
このルーチンは、呼び出されたのと同じスレッドで作られたデータベース接続のキャッシュから 少なくとも n バイトのメモリーを解放しようと試みます。 返される値は、実際に解放されたバイト数です。
SQLITE_ENABLE_MEMORY_MANAGMENT マクロ付きのコンパイルによってメモリー管理が 使用可能であった場合、このルーチンが利用可能です。
int sqlite3_reset(sqlite3_stmt *pStmt);
sqlite3_reset() 関数は、再実行の準備ができている、以前に sqlite3_prepare() あるいは sqlite3_prepare16() で得た構築済み SQL ステートメントを初期状態へリセットするために呼び出します。 sqlite3_bind_*() API を使って結合した値を持ついずれの SQL ステートメント変数も、それらの値を保持したままです。
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_text16be(sqlite3_context*, const void*, int n, void(*)(void*)); void sqlite3_result_text16le(sqlite3_context*, const void*, int n, void(*)(void*)); void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
ユーザー定義関数が戻り値を設定するためにこれらのルーチンを呼び出します。 sqlite3_result_value() ルーチンは関数に引数の１つの正確なコピーを返すために使われます。
これらのルーチンのオペレーションは sqlite3_bind_blob() ファミリーと非常に似ています。 そのドキュメントを読む事で詳しい情報を得てください。
void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
Register a callback to be invoked whenever a transaction is rolled back.
The new callback function overrides any existing rollback-hook callback. If there was an existing callback, then it's pArg value (the third argument to sqlite3_rollback_hook() when it was registered) is returned. Otherwise, NULL is returned.
For the purposes of this API, a transaction is said to have been rolled back if an explicit "ROLLBACK" statement is executed, or an error or constraint causes an implicit rollback to occur. The callback is not invoked if a transaction is automatically rolled back because the database connection is closed.
int sqlite3_set_authorizer( sqlite3*, int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), void *pUserData ); #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */ #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */ #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */ #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */ #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */ #define SQLITE_CREATE_VIEW 8 /* View Name NULL */ #define SQLITE_DELETE 9 /* Table Name NULL */ #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */ #define SQLITE_DROP_TABLE 11 /* Table Name NULL */ #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */ #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */ #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */ #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */ #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */ #define SQLITE_DROP_VIEW 17 /* View Name NULL */ #define SQLITE_INSERT 18 /* Table Name NULL */ #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ #define SQLITE_READ 20 /* Table Name Column Name */ #define SQLITE_SELECT 21 /* NULL NULL */ #define SQLITE_TRANSACTION 22 /* NULL NULL */ #define SQLITE_UPDATE 23 /* Table Name Column Name */ #define SQLITE_ATTACH 24 /* Filename NULL */ #define SQLITE_DETACH 25 /* Database Name NULL */ #define SQLITE_DENY 1 /* Abort the SQL statement with an error */ #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
This routine registers a callback with the SQLite library. The callback is invoked (at compile-time, not at run-time) for each attempt to access a column of a table in the database. The callback should return SQLITE_OK if access is allowed, SQLITE_DENY if the entire SQL statement should be aborted with an error and SQLITE_IGNORE if the column should be treated as a NULL value.
The second argument to the access authorization function will be one of the defined constants shown. These values signify what kind of operation is to be authorized. The 3rd and 4th arguments to the authorization function will be arguments or NULL depending on which of the following codes is used as the second argument. The 5th argument is the name of the database ("main", "temp", etc.) if applicable. The 6th argument is the name of the inner-most trigger or view that is responsible for the access attempt or NULL if this access attempt is directly from input SQL code.
The return value of the authorization function should be one of the constants SQLITE_OK, SQLITE_DENY, or SQLITE_IGNORE.
The intent of this routine is to allow applications to safely execute user-entered SQL. An appropriate callback can deny the user-entered SQL access certain operations (ex: anything that changes the database) or to deny access to certain tables or columns within the database.
int sqlite3_sleep(int);
Sleep for a little while. The second parameter is the number of miliseconds to sleep for.
If the operating system does not support sleep requests with milisecond time resolution, then the time will be rounded up to the nearest second. The number of miliseconds of sleep actually requested from the operating system is returned.
void sqlite3_soft_heap_limit(int N);
This routine sets the soft heap limit for the current thread to N. If the total heap usage by SQLite in the current thread exceeds N, then sqlite3_release_memory() is called to try to reduce the memory usage below the soft limit.
Prior to shutting down a thread sqlite3_soft_heap_limit() must be set to zero (the default) or else the thread will leak memory. Alternatively, use the sqlite3_thread_cleanup() API.
A negative or zero value for N means that there is no soft heap limit and sqlite3_release_memory() will only be called when memory is exhaused. The default value for the soft heap limit is zero.
SQLite makes a best effort to honor the soft heap limit. But if it is unable to reduce memory usage below the soft limit, execution will continue without error or notification. This is why the limit is called a "soft" limit. It is advisory only.
This routine is only available if memory management has been enabled by compiling with the SQLITE_ENABLE_MEMORY_MANAGMENT macro.
int sqlite3_step(sqlite3_stmt*);
sqlite3_prepare() あるいは sqlite3_prepare16() を呼び出してSQL クエリーを構築した後、 ステートメントを実行するために1回あるいは何度でもこの関数を呼び出さなくてはなりません。
戻り値は、 SQLITE_BUSY 、SQLITE_DONE 、 SQLITE_ROW 、 SQLITE_ERROR 、 SQLITE_MISUSE のどれかです。
SQLITE_BUSY は、ロックされているデータベースをデータベースエンジンが開こうとし、 尚且つ busy コールバックが登録されていなかったことを示します。 データベースのオープンをリトライするために、sqlite3_step() をもう一度呼んでください。
SQLITE_DONE は、ステートメントの実行が成功をもって終了したことを意味します。 sqlite3_step() を再度呼び出す場合は、はじめに sqlite3_reset() を呼び出して 仮想マシンを初期状態へリセットしなければなりません。
実行中の SQL ステートメントがデータを返す場合、呼び出し側による処理のために データの新しい行が用意され、何度でも SQLITE_ROW が返されます。 値にアクセスするためには、 sqlite3_column_*() 関数を使います。 データの次の行を検索するためには、再度 sqlite3_step() を呼びます。
SQLITE_ERROR は、（制約違反のような）ランタイムエラーの発生を意味します。 VM 上で再度 sqlite3_step() を呼び出してはいけません。 sqlite3_errmsg() を呼び出すことで、 さらなる情報を得られるかもしれません。
SQLITE_MISUSE は、このルーチンが不正に呼び出されたことを意味します。 おそらく、既に終了された仮想マシン、あるいは SQLITE_ERROR、SQLITE_DONE を返した 構築済みステートメントで呼び出したということです。 あるいは、データベース接続が作成されたのとは異なるスレッドで使われたという場合も あり得ます。
int sqlite3_table_column_metadata(
sqlite3 *db, /* Connection handle */
const char *zDbName, /* Database name or NULL */
const char *zTableName, /* Table name */
const char *zColumnName, /* Column name */
char const **pzDataType, /* OUTPUT: Declared data type */
char const **pzCollSeq, /* OUTPUT: Collation sequence name */
int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */
int *pPrimaryKey, /* OUTPUT: True if column part of PK */
int *pAutoinc /* OUTPUT: True if colums is auto-increment */
);
This routine is used to obtain meta information about a specific column of a specific database table accessible using the connection handle passed as the first function argument.
The column is identified by the second, third and fourth parameters to this function. The second parameter is either the name of the database (i.e. "main", "temp" or an attached database) containing the specified table or NULL. If it is NULL, then all attached databases are searched for the table using the same algorithm as the database engine uses to resolve unqualified table references.
The third and fourth parameters to this function are the table and column name of the desired column, respectively. Neither of these parameters may be NULL.
Meta information is returned by writing to the memory locations passed as the 5th and subsequent parameters to this function. Any of these arguments may be NULL, in which case the corresponding element of meta information is ommitted.
Parameter Output Type Description ----------------------------------- 5th const char* Declared data type 6th const char* Name of the columns default collation sequence 7th int True if the column has a NOT NULL constraint 8th int True if the column is part of the PRIMARY KEY 9th int True if the column is AUTOINCREMENT
The memory pointed to by the character pointers returned for the declaration type and collation sequence is valid only until the next call to any sqlite API function.
This function may load one or more schemas from database files. If an error occurs during this process, or if the requested table or column cannot be found, an SQLITE error code is returned and an error message left in the database handle (to be retrieved using sqlite3_errmsg()). Specifying an SQL view instead of a table as the third argument is also considered an error.
If the specified column is "rowid", "oid" or "_rowid_" and an INTEGER PRIMARY KEY column has been explicitly declared, then the output parameters are set for the explicitly declared column. If there is no explicitly declared IPK column, then the data-type is "INTEGER", the collation sequence "BINARY" and the primary-key flag is set. Both the not-null and auto-increment flags are clear.
This API is only available if the library was compiled with the SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
void sqlite3_thread_cleanup(void);
This routine ensures that a thread that has used SQLite in the past has released any thread-local storage it might have allocated. When the rest of the API is used properly, the cleanup of thread-local storage should be completely automatic. You should never really need to invoke this API. But it is provided to you as a precaution and as a potential work-around for future thread-releated memory-leaks.
int sqlite3_total_changes(sqlite3*);
This function returns the total number of database rows that have be modified, inserted, or deleted since the database connection was created using sqlite3_open(). All changes are counted, including changes by triggers and changes to TEMP and auxiliary databases. Except, changes to the SQLITE_MASTER table (caused by statements such as CREATE TABLE) are not counted. Nor are changes counted when an entire table is deleted using DROP TABLE.
See also the sqlite3_changes() API.
SQLite implements the command "DELETE FROM table" without a WHERE clause by dropping and recreating the table. (This is much faster than going through and deleting individual elements form the table.) Because of this optimization, the change count for "DELETE FROM table" will be zero regardless of the number of elements that were originally in the table. To get an accurate count of the number of rows deleted, use "DELETE FROM table WHERE 1" instead.
void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
Register a function that is called each time an SQL statement is evaluated. The callback function is invoked on the first call to sqlite3_step() after calls to sqlite3_prepare() or sqlite3_reset(). This function can be used (for example) to generate a log file of all SQL executed against a database. This can be useful when debugging an application that uses SQLite.
int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
Move all bindings from the first prepared statement over to the second. This routine is useful, for example, if the first prepared statement fails with an SQLITE_SCHEMA error. The same SQL can be prepared into the second prepared statement then all of the bindings transfered over to the second statement before the first statement is finalized.
void *sqlite3_update_hook(
sqlite3*,
void(*)(void *,int ,char const *,char const *,sqlite_int64),
void*
);
Register a callback function with the database connection identified by the first argument to be invoked whenever a row is updated, inserted or deleted. Any callback set by a previous call to this function for the same database connection is overridden.
The second argument is a pointer to the function to invoke when a row is updated, inserted or deleted. The first argument to the callback is a copy of the third argument to sqlite3_update_hook. The second callback argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending on the operation that caused the callback to be invoked. The third and fourth arguments to the callback contain pointers to the database and table name containing the affected row. The final callback parameter is the rowid of the row. In the case of an update, this is the rowid after the update takes place.
The update hook is not invoked when internal system tables are modified (i.e. sqlite_master and sqlite_sequence).
If another function was previously registered, its pArg value is returned. Otherwise NULL is returned.
See also: sqlite3_commit_hook(), sqlite3_rollback_hook()
void *sqlite3_user_data(sqlite3_context*);
The pUserData argument to the sqlite3_create_function() and sqlite3_create_function16() routines used to register user functions is available to the implementation of the function using this call.
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*); const void *sqlite3_value_text16be(sqlite3_value*); const void *sqlite3_value_text16le(sqlite3_value*); int sqlite3_value_type(sqlite3_value*);
これらのルーチン群は、ユーザー定義関数のために引数についての情報を返します。 関数の実装は、自身の引数へアクセスするためにこれらのルーチンを使います。 これらのルーチンが一つのsqlite3_value*を取り、sqlite3_column_...はsqlite3_stmt*と 整数のカラム番号を取ります。 それ以外の点は、これらのルーチンと sqlite3_column_... は同じです。
sqlite3_column_blob を見て追加の情報を得てください。