27.5. 近道インタフェース

Postgresは、サーバへの簡単な関数呼び出しを送信する近道 (fast-path) インタフェースを用意しています。

PQfn関数は、近道インタフェースを使ってサーバ関数の実行を要求します。

PGresult* PQfn(PGconn* conn,
               int fnid,
               int *result_buf,
               int *result_len,
               int result_is_int,
               const PQArgBlock *args,
               int nargs);

typedef struct {
    int len;
    int isint;
    union {
        int *ptr;
        int integer;
    } u;
} PQArgBlock;

fnid 引数は、実行する関数のOIDです。 args とnargsは関数に渡すパラメータを定義します。 これらは関数宣言における引数リストに一致しなければなりません。 パラメータ構造体のisintが真の場合、u.integerの値はサーバに指定長の整数として送信されます。 (これは1、2もしくは4バイトでなければなりません。) この時、適切なバイト順の交換が行なわれます。 isintが偽の場合は、*u.ptrで指定されたバイト数が無処理で送信されます。 関数のパラメータデータ型をバイナリ転送で行なうために、このデータはサーバで想定する書式である必要があります。 result_buf は戻り値を格納するバッファです。 呼び出し側は戻り値を格納するのに十分な領域を確保しておかなければいけません （ライブラリ側ではこのチェックはしていません！）。 結果の実データ長は result_len が指す整数で返されます。 結果が1、2、4 バイト整数だと想定できるなら result_is_int を 1 に、そうでなければ0を設定します。 result_is_int を 1 にすれば、必要に応じて値のバイト順を入れ換えるよう libpq に指示することになります。 そしてクライアントマシン上で正しいint値となるように転送します。 result_is_int が 0 の場合は、バックエンドが送ったバイナリ書式のバイト列を何も修正せずに返します。

PQfnは常に有効な PGresult* を返します。 結果を使う前にはまず、結果ステータスを調べておくべきでしょう。 結果が必要なくなった時点で、PQclearによって、PGresult を解放するのは、呼び出し側の責任です。

NULL引数やNULLの結果を扱うことができないことに注意してください。 このインタフェースを使用した場合、結果は値が設定されています。