27.2. Fonctions de statut de connexion

Renvoie le nom de la base de données de la connexion.

char *PQdb(const PGconn *conn);

Renvoie le nom d'utilisateur utilisé pour la connexion.

char *PQuser(const PGconn *conn);

Renvoie le mot de passe utilisé pour la connexion.

char *PQpass(const PGconn *conn);

Renvoie le nom d'hôte du serveur utilisé pour la connexion.

char *PQhost(const PGconn *conn);

Renvoie le numéro de port utilisé pour la connexion.

char *PQport(const PGconn *conn);

Renvoie le TTY de débogage pour la connexion. (Ceci est obsolète car le serveur ne fait plus attention au paramétrage du TTY mais les fonctions restent pour des raisons de compatibilité ascendante.)

char *PQtty(const PGconn *conn);

Renvoie les options en ligne de commande passées lors de la demande de connexion.

char *PQoptions(const PGconn *conn);

Renvoie l'état de la connexion.

ConnStatusType PQstatus(const PGconn *conn);

Le statut peut faire partie d'un certain nombre de valeurs. Néanmoins, seules deux ne concernent pas les procédures de connexion asynchrone : CONNECTION_OK et CONNECTION_BAD. Une bonne connexion de la base de données a l'état CONNECTION_OK. Une tentative échouée de connexion est signalée par le statut CONNECTION_BAD. D'habitude, un état OK reste ainsi jusqu'à PQfinish mais un problème de communications pourrait prématurément changer le statut en CONNECTION_BAD. Dans ce cas, l'application peut essayer de se récupérer en appelant PQreset.

Voir PQconnectStart ete PQconnectPoll pour connaître les autres statuts possibles.

Renvoie l'état actuel de la transaction du serveur.

PGTransactionStatusType PQtransactionStatus(const PGconn *conn);

Le statut peut être PQTRANS_IDLE (actuellement inactif), PQTRANS_ACTIVE (une commande est en cours), PQTRANS_INTRANS (inactif, dans un bloc valide de transaction) ou PQTRANS_INERROR (inactif, dans un bloc de transaction échoué). PQTRANS_UNKNOWN est reporté si la connexion est mauvaise. PQTRANS_ACTIVE est reporté seulement quand une requête a été envoyée au serveur mais qu'elle n'est pas terminée.

Recherche un paramétrage actuel du serveur.

const char *PQparameterStatus(const PGconn *conn, const char *paramName);

Certaines valeurs de paramètres sont reportées par le serveur automatiquement ou lorsque leur valeurs changent. PQparameterStatus peut être utilisé pour interroger ces paramétrages. Il renvoie la valeur actuelle d'un paramètre s'il est connu et NULL dans le cas contraire.

Les paramètres reportés pour la version actuelle incluent server_version (ne peut pas changer après le lancement du serveur) ; client_encoding, is_superuser, session_authorization et datestyle.

Les serveurs utilisant un protocole antérieur à la version 3.0 ne reportent pas la configuration des paramètres mais libpq inclut la logique pour obtenir des valeurs pour server_version et client_encoding. Les applications sont encouragées à utiliser PQparameterStatus plutôt qu'un code ad-hoc modifiant ces valeurs. (Néanmoins, attention, les connexions pré-3.0, un changement de client_encoding via SET après le lancement de la connexion n'est pas reflété par PQparameterStatus.)

Demande la version du protocole client/serveur utilisé.

int PQprotocolVersion(const PGconn *conn);

Les applications peuvent souhaiter utiliser ceci pour déterminer si certaines fonctionnalités sont supportées. Actuellement, les seules valeurs possible sont 2 (protocole 2.0), 3 (protocole 3.0) ou zéro (mauvaise connexion). Ceci ne change pas après la fin du lancement de la connexion mais peut théoriquement être changé après une réinitialisation. Le protocole 3.0 est normalement utilisé lors de la communication avec les serveurs PostgreSQL 7.4 ou ultérieures ; les serveurs antérieurs à la 7.4 supportent uniquement le protocole 2.0. (Le protocole 1.0 est obsolète et non supporté par libpq.)

Renvoie le dernier message d'erreur généré par une opération sur la connexion.

char *PQerrorMessage(const PGconn* conn);

Pratiquement toutes les fonctions libpq initialisent un message pour PQerrorMessage en cas d'échec. Notez que par convention, dans libpq, un résultat non vide de PQerrorMessage inclue un retour chariot à la fin.

Obtient le descripteur de fichier de la socket de la connexion au serveur. Un descripteur valide est plus grand ou égal à 0 ; un résultat de -1 indique qu'aucune connexion au serveur n'est actuellement ouverte. (Ceci ne change pas lors de l'opération normale mais peut changer lors de l'initialisation ou de la réinitialisation d'une connexion.)

int PQsocket(const PGconn *conn);

Renvoie l'identifiant du processus (PID) du serveur gérant cette connexion.

int PQbackendPID(const PGconn *conn);

Le PID du moteur est utile pour des raisons de débogage et pour la comparaison avec les messages NOTIFY (qui indiquent le PID du processus serveur lançant la notification). Notez que le PID appartient à un processus exécuté sur l'hôte du serveur de bases de données et non pas sur l'hôte local !

Retourne la structure SSL utilisée dans la connexion ou NULL si SSL n'est pas utilisé.

SSL *PQgetssl(const PGconn *conn);

Cette structure peut être utilisée pour vérifier les niveaux de cryptage, pour vérifier les certificats du serveur, et plus. Référez-vous à la documentation d'OpenSSL pour plus d'informations sur cette structure.

Vous pouvez définir USE_SSL pour obtenir le prototype de cette fonction. Faire cela inclura automatiquement ssl.h à partir de OpenSSL.