伺服器生成的通知和警告訊息不會被查詢執行函式返回,因為它們並不意味著查詢失敗。相反,它們會被傳遞給通知處理函式,並在處理函式返回後正常繼續執行。預設的通知處理函式會將訊息列印到 stderr
,但應用程式可以透過提供自己的處理函式來覆蓋此行為。
出於歷史原因,通知處理分為兩個級別,稱為通知接收器(notice receiver)和通知處理器(notice processor)。預設行為是通知接收器格式化通知並將字串傳遞給通知處理器進行列印。然而,選擇提供自己的通知接收器的應用程式通常會忽略通知處理器層,而只在通知接收器中完成所有工作。
函式 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
這樣的函式可能使用。
如果您在文件中發現任何不正確、與您對特定功能的體驗不符或需要進一步闡明的內容,請使用 此表單 報告文件問題。