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 NULL, 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 d'obtenir le message complet préformaté en utilisant
PQresultErrorMessage
ou PQresultVerboseErrorMessage
). 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,
fourni en format texte. La chaîne texte du message est passée (avec un retour
chariot final), 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 courants de
PGconn
sont copiés dans PGresult
pour une
utilisation possible par des fonctions comme PQgetvalue
.