雑多な関数

PostgreSQL 9.1.1文書
前のページ | 巻戻し | 第 31章libpq - C ライブラリ | 早送り | 次のページ

# 31.10. 雑多な関数

よくあることですが、うまく分類できない関数がいくつか存在します。

`PQfreemem`

  libpqが割り当てたメモリを解放します。

      void PQfreemem(void *ptr);

  具体的には`PQescapeByteaConn`、`PQescapeBytea`、`PQunescapeBytea`および`PQnotifies`によりlibpqが割り当てたメモリを解放します。 Microsoft Windowsにおいて`free()`ではなく、この関数を使用することが特に重要です。 DLLにおけるメモリ割り当てとアプリケーションにおけるその解放が、DLLとアプリケーションとでマルチスレッド/シングルスレッド、リリース用/デバッグ用、静的/動的フラグが同じ場合でのみ動作するためです。 Microsoft Windowsプラットフォーム以外では、この関数は標準ライブラリの`free()`関数と同じです。

`PQconninfoFree`

  `PQconndefaults`もしくは`PQconninfoParse`が割り当てたデータ構造を解放します。

      void PQconninfoFree(PQconninfoOption *connOptions);

  単純な`PQfreemem`は、配列が補助文字列への参照を含んでいることから、このためには作業しません。

`PQencryptPassword`

  PostgreSQLパスワードの暗号化された形式を準備します。

      char * PQencryptPassword(const char *passwd, const char *user);

  この関数は、`ALTER USER joe PASSWORD 'pwd'`のようなコマンドを送信したいクライアントアプリケーションで使用されることを意図したものです。 こうしたコマンドでは、コマンドログが活動の監視などで晒されてしまうため、元々の平文テキストでパスワードを送信しないことが推奨されています。 その代わりに、この関数を使用して送信前にパスワードを暗号化形式に変換してください。 引数は平文のパスワードとそのSQL上のユーザ名です。 戻り値は`malloc`で割り当てられた文字列です。 メモリ不足の場合に`NULL`が返されます。 呼び出し元は、その文字列にエスケープしなければならない特殊な文字列が含まれていないことを仮定することができます。 処理が終わった時に`PQfreemem`を使用して結果を解放してください。

`PQmakeEmptyPGresult`

  与えられたステータスで空の`PGresult`オブジェクトを構築します。

      PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);

  これは空の`PGresult`オブジェクトを割り当てて、初期化するlibpqの内部関数です。 メモリが割り当てられなかった場合、この関数は`NULL`を返します。 一部のアプリケーションで結果オブジェクト（特にエラーステータスを伴ったオブジェクト）それ自身を生成することが便利であることが分かりましたので、外部公開されました。 `conn`が非ヌルで、`status`がエラーを示唆している場合、特定された接続の現在のエラーメッセージは`PGresult`にコピーされます。 同時に、`conn`が非ヌルの場合、接続で登録された任意のイベントプロシージャは`PGresult`にコピーされます。 （それらは`PGEVT_RESULTCREATE`呼び出しを受けませんが、`PQfireResultCreateEvents`を理解します。） libpq自身で返された`PGresult`と同様に、最終的にはこのオブジェクトに対して`PQclear`を呼び出さなければならないことに注意してください。

`PQfireResultCreateEvents`

  `PGresult`オブジェクトに登録されたそれぞれのイベントプロシージャに対し、`PGEVT_RESULTCREATE`イベント（項31.12を参照）を発行します。 イベントプロシージャが成功の場合は非ゼロ、失敗の場合はゼロを返します。

      int PQfireResultCreateEvents(PGconn *conn, PGresult *res);

  `conn`引数はイベントプロシージャに渡されますが、直接には使用されません。 イベントプロシージャが使用しない場合は`NULL`です。

  このオブジェクトに対し、`PGEVT_RESULTCREATE`もしくは`PGEVT_RESULTCOPY`イベントを過去に受け取ったイベントプロシージャは再び発行されません。

  この関数が`PQmakeEmptyPGResult`と分離されている主たる理由は、多くの場合イベントプロシージャを呼び出す前に`PGresult`を作成し、データを挿入するのが適切であることによります。

`PQcopyResult`

  `PGresult`オブジェクトのコピーを作ります。 コピーは元の結果にいかなる方法でもリンクされず、コピーが不要になった時に`PQclear`を呼び出されなければなりません。 関数が失敗すると`NULL`が返されます。

      PGresult *PQcopyResult(const PGresult *src, int flags);

  これは正確なコピーの作成を目的としたものではありません。 返された結果は常に`PGRES_TUPLES_OK`状態の中に置かれ、元の結果におけるエラーメッセージはまったくコピーされません。 （しかしコマンド状態文字列をコピーします。） `flags`引数はその他にコピーするものがないかを決定します。 それはいくつかのフラグのビット単位のORです。 `PG_COPYRES_ATTRS`は元の結果の属性（列定義）のコピーを指定します。 `PG_COPYRES_TUPLES`は元の結果のタプルのコピーを指定します。 （これは属性もコピーされることを意味しています。） `PG_COPYRES_NOTICEHOOKS`は元の結果の警告フックのコピーを指定します。 `PG_COPYRES_EVENTS`は元の結果イベントのコピーを指定します。 （しかし、元の結果に関連したインスタンスデータはまったくコピーされません。）

`PQsetResultAttrs`

  `PGresult`オブジェクトの属性を設定します。

      int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);

  提供された`attDescs`は結果にコピーされます。 もし`attDescs`ポインタが`NULL`、または`numAttributes`が１未満の場合、要求は無視され、関数は成功します。 `res`が既に属性を所有している場合、関数は失敗に終わります。 関数が失敗すると、戻り値はゼロです。 関数が成功すると戻り値は非ゼロになります。

`PQsetvalue`

  `PGresult`オブジェクトのタプルフィールド値を設定します。

      int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);

  必要に応じて関数は自動的に結果の内部タプル配列を肥大化させます。 しかし、`tup_num`引数は`PQntuples`と同じか、もしくは小さくなければなりません。 その意味は、この関数は一回にタプル配列を１タプル大きくさせるだけだからです。 とは言っても、存在するいかなるタプルの任意のフィールドも、順序を問わず変更できます。 もし`field_num`に値が既に存在すれば、書き換えられます。 `len`が-1、または`value`が`NULL`であれば、フィールドの値はSQLのNULLに設定されます。 `value`は結果のプライベート格納領域にコピーされるため、関数が返った後ではもう必要がなくなります。 関数が失敗すると、戻り値はゼロです。 関数が成功すると戻り値は非ゼロになります。

`PQresultAlloc`

  `PGresult`オブジェクトに補助ストレージを割り当てます。

      void *PQresultAlloc(PGresult *res, size_t nBytes);

  `res`が消去された時、この関数で割り付けられたメモリは解放されます。 関数が失敗すると戻り値は`NULL`です。 `malloc`と同じように、どのような種類のデータでも結果は適切に整列されることが保証されています。

`PQlibVersion`

  使用中のlibpqのバージョンを返します。

      int PQlibVersion(void);

  この関数の結果を使用して、実行時に現在読み込まれているバージョンのlibpqで特定の機能が利用可能かどうかを決定することができます。 例えばこの関数を使用して、`PQconnectdb`でどの接続オプションが利用できるか、PostgreSQL 9.0で追加された`hex` `bytea`出力をサポートするかを確認することができます。

  この数値の形式は、メジャー、マイナー、リビジョン番号を2桁の10進数に変換し、連結させたものです。 例えば、バージョン9.1では90100を返し、バージョン9.1.2では90102を返します。 （先頭の0は現れません。）

  > 注意: この関数はPostgreSQLバージョン9.1で追加されました。 このため以前のバージョンにおいて要求される機能を検知するために使用することができません。 この関数へのリンク処理がバージョン9.1とのリンク依存性を作成するためです。

前のページ | ホーム | 次のページ
制御関数 | 上に戻る | 警告処理