27.10. Traitement des messages

Les messages de note et d'avertissement g�n�r�s par le serveur ne sont pas renvoy�s par les fonctions d'ex�cution des requ�tes car elles n'impliquent pas d'�chec dans la requ�te. � la place, elles sont pass�es � la fonction de gestion des messages et l'ex�cution continue normalement apr�s le retour du gestionnaire. La fonction par d�faut de gestion des messages affiche le message sur stderr mais l'application peut surcharger ce comportement en proposant sa propre fonction de gestion.

Pour des raisons historiques, il existe deux niveaux de gestion de messages, appel�s la r�ception des messages et le traitement. Pour la r�ception, le comportement par d�faut est de formater le message et de passer une cha�ne au traitement pour affichage. N�anmoins, une application qui choisit de fournir son propre receveur de messages ignorera typiquement la couche d'envoi de messages et effectuera tout le travail au niveau du receveur.

La fonction PQsetNoticeReceiver initialise ou examine le receveur actuel de messages pour un objet de connexion. De la m�me fa�on, PQsetNoticeProcessor initialise ou examine l'�metteur actuel de messages.

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);

Chacune de ces fonctions re�oit le pointeur de fonction du pr�c�dent receveur ou �metteur de messages et configure la nouvelle valeur. Si vous fournissez un pointeur de fonction nul, aucune action n'est r�alis�e mais le pointeur actuel est renvoy�.

Quand un message de note ou d'avertissement est re�u du serveur ou g�n�r� de fa�on interne par libpq, la fonction de r�ception du message est appel�e. Le message lui est pass� sous la forme d'un PGresult PGRES_NONFATAL_ERROR (ceci permet au receveur d'extraire les champs individuels en utilisant PQresultErrorField ou le message complet pr�format� en utilisant PQresultErrorMessage). Le m�me pointeur void pass� � PQsetNoticeReceiver est aussi renvoy� (ce pointeur peut �tre utilis� pour acc�der � un �tat sp�cifique de l'application si n�cessaire).

Le receveur de messages par d�faut extrait simplement le message (en utilisant PQresultErrorMessage) et le passe au syst�me de traitement du message.

Ce dernier est responsable de la gestion du message de note ou d'avertissement donn� au format texte. La cha�ne texte du message est pass�e avec un retour chariot suppl�mentaire, plus un pointeur sur void identique � celui pass� � PQsetNoticeProcessor (ce pointeur est utilis� pour acc�der � un �tat sp�cifique de l'application si n�cessaire).

Le traitement des messages par d�faut est simplement

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

Une fois que vous avez initialis� un receveur ou une fonction de traitement des messages, vous devez vous attendre � ce que la fonction soit appel�e aussi longtemps que l'objet PGconn ou qu'un objet PGresult r�alis� � partir de celle-ci existent. � la cr�ation d'un PGresult, les pointeurs de gestion actuels de PGconn sont copi�s dans PGresult pour une utilisation possible par des fonctions comme PQgetvalue.