Senna2 API解説

Senna1.1以降で追加されるSenna Query Language API(QL API)について説明します。

QL APIは2つのデータ型とその操作関数で構成されています。

sen_db 型

永続的な複数のテーブルからなるデータベースに対応するデータ型です。 スタンドアロンモードでデータベースを使用する場合には、 sen_dbのインスタンスが必要になります。

sen_db *sen_db_create(const char *path, int flags, sen_encoding encoding);

pathで与えられた新しいデータベースを作成し、対応するsen_dbインスタンスを返します。 失敗した場合にはNULLを返します。flagsにはテーブル名を管理するsymに対するflag情報を指定します。通常は0を指定してください。encodingは、作成するデータベースでデフォルトで使用される文字エンコーディングを指定します。(現状では、問合せ言語にリテラルとして渡した文字列も全てここに指定したエンコーディングに従って解釈されます)

sen_db *sen_db_open(const char *path);

pathで与えられた既に作成済のデータベースを開き、 対応するsen_dbインスタンスを返します。 失敗した場合はNULLを返します。

sen_rc sen_db_close(sen_db *db);

dbに対応するデータベースを閉じ、sen_dbインスタンスを解放します。 成功すれば sen_success が、失敗すればエラーコードが返ります。

sen_ctx 型

データベースへの接続に対応するデータ型です。データベースを操作する際に必要になります。 同一のデータベースに対して複数のsen_ctxを張っても構いません。

sen_ctx *sen_ctx_open(sen_db *db, int flags);

同一プロセス内にロードされたsen_dbインスタンスに対して接続を行い、対応するsen_ctxインスタンスを返します。flagsには、以下が指定できます。失敗した場合にはNULLを返します。

SEN_CTX_USEQL

問合せ言語の使用の有無(現状では必須)

SEN_CTX_BATCHMODE

入力した式の評価結果の表示/非表示

sen_ctx *sen_ctx_connect(const char *host, int port, int flags);

hostに対応するホストの、portに対応するポート番号に対して接続を行い、対応するsen_ctxインスタンスを返します。flagsには、sen_ctx_openと同じものが指定できます。失敗した場合にはNULLを返します。

sen_rc sen_ctx_load(sen_ctx *ctx, const char *path);

pathで与えられるファイルの内容をctxのインタープリタにロードします。

sen_rc sen_ctx_send(sen_ctx *ctx, char *str, unsigned int str_len, int flags);

長さstr_lenバイトの文字列strをctxのインタープリタに評価させます。flagには以下が指定できます。

SEN_CTX_MORE

式が終端していない(まだ続きがある)ことを示します。

sen_rc sen_ctx_recv(sen_ctx *ctx, char **str, unsigned int *str_len, int *flags);

sen_ctx_sendで与えた文字列をctxのインタープリタが評価した結果として得られた出力を受け取ります。str, str_len, flagsは出力パラメータで、呼出し元で準備した実体に対するポインタを渡します。strに返される文字列を解放する必要はありません。ctxがクライアントモードで作成されている場合、受け取るべき出力が到着するまで待ちます。flagsに返される値のSEN_CTX_MORE bitが立っている場合は、まだ続きがあることを示します。

sen_rc sen_ctx_close(sen_ctx *ctx);

ctxに対応するsen_ctxの接続を解除し、関連する資源を解放します。

sen_rc sen_ctx_info_get(sen_ctx *ctx, sen_ctx_info *info);

ctxに関する情報を取得します。infoは出力パラメータで、呼出し元で準備した実体に対するポインタを渡します。ctxがクライアントモードで作成されている場合は、対応するTCPソケットのファイル識別子がinfo.fdに返されますので、selectやpollコールを使って次のデータがいつ届くかを判断できます。