PostgreSQL 中文参考文档
🌐 英文原版 官方 ↗

32.13. Notice 提示消息处理 #

由服务器生成的通知和警告消息不会被查询执行函数返回, 因为它们并不意味着查询失败。 作为替代, 它们会被传递给一个通知处理函数, 并且在处理器返回之后继续正常执行。 默认的通知处理函数把消息打印到 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) 并把它传递给通知处理器。

通知处理器负责处理以文本形式给出的通知或警告消息。 消息的字符串文本 (包括一个结尾的换行符) 会被传递给它, 再加上一个 void 指针, 它与传递给 PQsetNoticeProcessor 的是同一个。 (这个指针可用于在需要时访问应用特定的状态。)

默认的通知处理器很简单:

static void
defaultNoticeProcessor(void *arg, const char *message)
{
    fprintf(stderr, "%s", message);
}

一旦你设置了一个通知接收器或处理器, 你就应当预期, 只要 PGconn 对象或由它产生的 PGresult 对象还存在, 那个函数就可能被调用。 在一个 PGresult 被创建时, PGconn 当前的通知处理指针会被复制到该 PGresult 中, 以供诸如 PQgetvalue 之类的函数在可能的情况下使用。