27.10. 注意訊息處理

伺服器生成的注意訊息和警告訊息都不會由查詢執行函數返回，因為他們並不蘊涵這查詢的失敗。 它們會被傳遞給一個注意訊息處理函數，然後在該處理返回之後繼續正常執行。 預設的注意訊息處理函數在 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 這樣的函數使用。