支援的版本:目前 (17) / 16 / 15 / 14 / 13
開發版本:devel
不再支援的版本:12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4

32.13. 通知處理 #

伺服器產生的通知和警告訊息不會由查詢執行函式傳回,因為它們不代表查詢失敗。相反地,它們會傳遞給通知處理函式,並且在處理常式傳回後繼續正常執行。預設的通知處理函式會將訊息列印在 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);

這些函式都會傳回先前的通知接收器或處理器函式指標,並設定新值。如果您提供 null 函式指標,則不會採取任何動作,但會傳回目前的指標。

當從伺服器收到通知或警告訊息,或由 libpq 內部產生時,會呼叫通知接收器函式。它會以 PGRES_NONFATAL_ERROR PGresult 的形式傳遞訊息。(這允許接收器使用 PQresultErrorField 提取個別欄位,或使用 PQresultErrorMessagePQresultVerboseErrorMessage 取得完整的預先格式化訊息。)傳遞給 PQsetNoticeReceiver 的相同 void 指標也會被傳遞。(如果需要,此指標可用於存取應用程式特定的狀態。)

預設的通知接收器僅提取訊息(使用 PQresultErrorMessage)並將其傳遞給通知處理器。

通知處理器負責處理以文字形式給出的通知或警告訊息。它會傳遞訊息的字串文字(包括尾隨換行符),以及一個 void 指標,該指標與傳遞給 PQsetNoticeProcessor 的指標相同。(如果需要,此指標可用於存取應用程式特定的狀態。)

預設的通知處理器很簡單,如下所示:

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

一旦您設定了通知接收器或處理器,您應該預期只要 PGconn 物件或從它建立的 PGresult 物件存在,就可以呼叫該函式。在建立 PGresult 時,PGconn 的目前通知處理指標會被複製到 PGresult 中,以供 PQgetvalue 之類的函式可能使用。

提交更正

如果您在文件中發現任何不正確、與您特定功能的體驗不符或需要進一步澄清的內容,請使用此表單報告文件問題。