pgsql.cc 提供对 postgresql.org 官网内容的中文翻译,由 Pigsty 团队维护。
服务器生成的通知和警告消息不由查询执行函数返回,因为它们并不表示查询失败。这些消息会传递给通知处理函数,处理函数返回后,执行正常继续。默认通知处理函数将消息打印到 stderr,应用程序也可以提供自己的处理函数来替换这一行为。
由于历史原因,通知处理有两个级别,称为通知接收器和通知处理器。通知接收器的默认行为是格式化通知并且将一个字符串传递给通知处理器来打印。不过,如果一个应用选择提供自己的通知接收器,它通常会忽略通知处理器层并且在通知接收器中完成所有工作。
函数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);
这些函数中的每一个会返回之前的通知接收器或处理器函数指针,并且设置新值。如果你提供了一个空函数指针,将不会采取任何动作,只会返回当前指针。
从服务器收到通知或警告消息,或者 libpq 内部生成这类消息时,便会调用通知接收器函数。消息以状态为 PGRES_NONFATAL_ERROR 的 PGresult 对象传给该函数。(接收器可使用 PQresultErrorField 提取单个字段,或使用 PQresultErrorMessage 获取完整的预格式化消息。)传给 PQsetNoticeReceiver 的同一个 void 指针也会传入。(必要时,可通过该指针访问应用程序特有的状态。)
默认的通知接收器会简单地抽取消息(使用PQresultErrorMessage)并且将它传递给通知处理器。
通知处理器负责处理以文本形式提供的通知或警告消息。传给它的参数包括消息字符串(含末尾的换行符),以及先前传给 PQsetNoticeProcessor 的同一个 void 指针。(必要时,可通过该指针访问应用程序特有的状态。)
默认的通知处理器很简单:
static void
defaultNoticeProcessor(void *arg, const char *message)
{
fprintf(stderr, "%s", message);
}
设置通知接收器或处理器后,应当预期:只要 PGconn 对象或由它生成的 PGresult 对象仍存在,就可能调用该函数。创建 PGresult 时,会将 PGconn 当前的通知处理指针复制到 PGresult 中,供 PQgetvalue 等函数在需要时使用。
译文有误、术语不当或页面显示问题,请到译文仓库 pgsty/pgdoc 报告译文问题。 英文原文本身的问题,请在当前版本的对应页面向上游反馈;上游不再修订已结束维护的版本。