問い合わせ実行関数では、サーバにより生成された通知と警告メッセージは、問い合わせの失敗を意味していないので返されません。
その代わり、それらは通知処理関数に渡され、ハンドラから返った後も実行は通常通り継続します。
デフォルトの通知処理関数はstderr
にメッセージを出力しますが、アプリケーションは自身の処理関数を提供することでこの動作を書き換えることができます。
歴史的理由で、通知レシーバと通知プロセッサと呼ばれる2階層の通知処理が存在します。 デフォルトの動作は、通知レシーバが通知を書式化し、出力のため通知プロセッサに文字列を渡します。 しかし、独自の通知レシーバを提供することを選んだアプリケーションでは、通常、通知プロセッサ層を無視し、すべての作業を単に通知レシーバで行います。
関数PQsetNoticeReceiver
は接続オブジェクトに対し現在の通知レシーバを設定もしくは確認します。
同様に、PQsetNoticeProcessor
は現在の通知プロセッサの設定もしくは確認を行います。
typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res); PQnoticeReceiver PQsetNoticeReceiver(PGconn *conn, PQnoticeReceiver proc, void *arg); typedef void (*PQnoticeProcessor) (void *arg, const char *message); PQnoticeProcessor PQsetNoticeProcessor(PGconn *conn, PQnoticeProcessor proc, void *arg);
各関数は、以前の通知レシーバもしくは通知プロセッサ用の関数へのポインタを返し、新しい値を設定します。 関数ポインタにNULLを渡した場合、何も変更されず、現在のポインタが返されるだけです。
サーバから注意/警告メッセージを受け取ると、あるいは、libpq内部で注意/警告メッセージが生成されると、通知レシーバ関数が呼び出されます。
PGRES_NONFATAL_ERROR
PGresult
という形でメッセージが渡されます。
(これにより、レシーバはPQresultErrorField
を使用して個々のフィールドを取り出すことや、PQresultErrorMessage
あるいはPQresultVerboseErrorMessage
を使用して事前に整形された完全なメッセージを取得することができます。)
PQsetNoticeReceiver
に渡されたvoidポインタと同じものも渡されます。
(このポインタを使用して、必要に応じてアプリケーション特有の状態にアクセスすることができます。)
デフォルトの通知レシーバは単に(PQresultErrorMessage
を使用して)メッセージを取り出し、それを通知プロセッサに渡すだけです。
通知プロセッサは、テキスト形式で与えられた注意/警告メッセージの取扱いに責任を持ちます。
メッセージは(最後の改行を含む)文字列テキストで渡され、更に、PQsetNoticeProcessor
に渡したものと同じvoidポインタも渡されます。
(このポインタを使用して、必要に応じてアプリケーション特有の状態にアクセスすることができます。)
デフォルトの通知プロセッサは以下のような単純なものです。
static void defaultNoticeProcessor(void *arg, const char *message) { fprintf(stderr, "%s", message); }
一旦通知レシーバや通知プロセッサを設定したら、PGconn
オブジェクトか、それから生成されたPGresult
オブジェクトが存在している間は、その関数が呼び出される可能性があると考えておくべきです。
PGresult
の生成時には、PGconn
の現在の警告処理用のポインタが、PQgetvalue
のような関数で使用可能であるように、PGresult
へコピーされます。