服务器生成的通知和警告消息不会由查询执行函数返回,因为它们并不意味着查询失败。相反,它们会传递给通知处理函数,并且在处理函数返回后继续正常执行。默认的通知处理函数会在 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
或 PQresultVerboseErrorMessage
获取完整的预格式化消息。)传递给 PQsetNoticeReceiver
的同一个 void 指针也会被传递。(如果需要,此指针可用于访问应用程序特定的状态。)
默认的通知接收器只是提取消息(使用 PQresultErrorMessage
),并将其传递给通知处理器。
通知处理器负责处理以文本形式给出的通知或警告消息。它会收到消息的字符串文本(包括尾随换行符),以及传递给 PQsetNoticeProcessor
的同一个 void 指针。(如果需要,此指针可用于访问应用程序特定的状态。)
默认的通知处理器很简单
static void defaultNoticeProcessor(void *arg, const char *message) { fprintf(stderr, "%s", message); }
一旦您设置了通知接收器或处理器,您应该预期,只要 PGconn
对象或由它生成的 PGresult
对象存在,就可能会调用该函数。在创建 PGresult
时,PGconn
的当前通知处理指针会被复制到 PGresult
中,以便供 PQgetvalue
等函数使用。
如果您在文档中发现任何不正确、与您特定功能的使用体验不符或需要进一步澄清的内容,请使用此表单报告文档问题。