Генерируемые сервером сообщения об уведомлениях и предупреждениях не возвращаются функциями выполнения запросов, поскольку они не указывают на сбой запроса. Вместо этого они передаются функции обработки уведомлений, и после завершения работы данного обработчика выполнение продолжается в обычном режиме. Стандартная функция обработки уведомлений выводит сообщение в поток
stderr, однако приложение может переопределить данное поведение путем предоставления собственной функции обработки.
По историческим причинам существует два уровня обработки уведомлений: получатель уведомлений (notice receiver) и процессор уведомлений (notice processor). По умолчанию получатель уведомлений форматирует уведомление и передает строку процессору уведомлений для последующего вывода. Однако если в приложении решено использовать собственный приемник уведомлений, то уровень процессора уведомлений обычно игнорируется, а вся работа выполняется непосредственно в приемнике уведомлений.
Функция PQsetNoticeReceiver
устанавливает или
опрашивает текущий приемник уведомлений для объекта conn.
Аналогично, 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, the notice receiver function is called. Сообщение передается данной функции в виде
типа PGRES_NONFATAL_ERROR
PGresult. (Это позволяет приемнику извлекать
отдельные поля с помощью функции PQresultErrorField, или получать полное предварительно отформатированное сообщение с помощью функции PQresultErrorMessage
или PQresultVerboseErrorMessage.) Тот же
указатель void, переданный функции PQsetNoticeReceiver также
передается. (Данный указатель может использоваться для доступа к состоянию приложения, если это необходимо.)
Стандартная функция получения уведомлений просто извлекает сообщение (используя функцию
PQresultErrorMessage) и передает его функции обработки уведомлений.
Функция обработки уведомлений отвечает за обработку уведомлений или предупреждающих сообщений, представленных в текстовом виде. В эту функцию передается текст сообщения в виде строки
(включая завершающий символ новой строки), а также указатель типа void, идентичный
передаваемому в функцию PQsetNoticeProcessor. (Данный указатель
может быть использован для доступа к состоянию конкретного приложения при необходимости.)
Стандартная функция обработки уведомлений выглядит следующим образом:
static void
defaultNoticeProcessor(void *arg, const char *message)
{
fprintf(stderr, "%s", message);
}
После установки функции приема или обработки уведомлений следует ожидать, что эта функция может вызываться до тех пор, пока существуют либо
PGconn объекта или PGresult созданные на его основе объекты. При создании объекта PGresult, the
PGconnтекущие указатели обработки уведомлений копируются в PGresult для возможного использования такими функциями, как
PQgetvalue.