27.9. Traitement des messages

Les messages d'information 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 récepteur de messages ignore habituellement la couche de traitement de messages et fait tout travail au niveau du récepteur.

La fonction PQsetNoticeReceiver initialise ou examine le récepteur actuel de messages pour un objet de connexion. De la même façon, PQsetNoticeProcessor initialise ou examine le processeur 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 retourne le pointeur de fonction du précédent récepteur ou du processeur de messages et configure la nouvelle valeur. Si vous fournissez un pointeur de fonction nul, aucun changement n'est réalisé 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 de type PGRES_NONFATAL_ERROR. (Ceci permet au récepteur 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 passé. (Ce pointeur peut être utilisé pour accéder à un état spécifique de l'application si nécessaire.)

Le récepteur 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, plus un pointeur sur void identique à celui passé à PQsetNoticeProcessor. (Ce pointeur peut être 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 récepteur 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 éventuelle utilisation par des fonctions comme PQgetvalue.