PostgreSQLLa base de données la plus sophistiquée au monde.

Version anglaise

32.2. Fonctions de statut de connexion

Ces fonctions sont utilisées pour interroger le statut d'un objet de connexion existant.

[Astuce]

Astuce

Les développeurs d'application libpq devraient être attentif au maintien de leur abstraction PGconn. Utilisez les fonctions d'accès décrites ci-dessous pour obtenir le contenu de PGconn. Référence les champs internes de PGconn en utilisant libpq-int.h n'est pas recommandé parce qu'ils sont sujets à modification dans le futur.

Les fonctions suivantes renvoient les valeurs des paramètres utilisés pour la connexion. Ces valeurs sont fixes pour la durée de vie de l'objet PGconn.

PQdb

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

char *PQdb(const PGconn *conn);
       
PQuser

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

char *PQuser(const PGconn *conn);
       
PQpass

Renvoie le mot de passe utilisé pour la connexion.

char *PQpass(const PGconn *conn);
       
PQhost

Renvoie le nom d'hôte du serveur utilisé pour la connexion. Cela peut être un nom d'hôte, une adresse IP ou un chemin de répertoire (pour ce dernier, ceci ne survient que si la connexion est réalisée via un socket Unix). Le cas du chemin peut être distingué car il sera toujours un chemin absolu, commençant avec /.)

char *PQhost(const PGconn *conn);
       
PQport

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

char *PQport(const PGconn *conn);
       
PQtty

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

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

char *PQoptions(const PGconn *conn);
       

Les fonctions suivantes renvoient le statut car il peut changer suite à l'exécution d'opérations sur l'objet PGconn.

PQstatus

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 restera ainsi jusqu'à PQfinish mais un échec de communications pourrait résulter en un statut changeant prématurément CONNECTION_BAD. Dans ce cas, l'application pourrait essayer de récupérer en appelant PQreset.

Voir l'entrée de PQconnectStartParams, PQconnectStart et de PQconnectPoll en regard aux autres codes de statut, qui pourraient être renvoyés.

PQtransactionStatus

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.

PQparameterStatus

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 si le paramètre est inconnu.

Les paramètres reportés pour la version actuelle incluent server_version, server_encoding, client_encoding, application_name, is_superuser, session_authorization, datestyle, IntervalStyle, TimeZone, integer_datetimes et standard_conforming_strings. (server_encoding, TimeZone et integer_datetimes n'étaient pas rapportés dans les versions antérieures à la 8.0 ; standard_conforming_strings n'était pas rapporté dans les versions antérieures à la 8.1; IntervalStyle n'était pas rapporté dans les versions antérieures à la 8.4; application_name n'était pas rapporté dans les versions antérieures à la 9.0). Notez que server_version, server_encoding et integer_datetimes ne peuvent pas changer après le lancement du serveur.

Les serveurs utilisant un protocole antérieur à la 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, changeant client_encoding via SET après le lancement de la connexion, ne seront pas reflétées par PQparameterStatus). Pour server_version, voir aussi PQserverVersion, qui renvoie l'information dans un format numérique qui est plus facile à comparer.

Si aucune valeur n'est indiquée pour standard_conforming_strings, les applications pourraient supposer qu'elle vaut off, c'est-à-dire que les antislashs sont traités comme des échappements dans les chaînes littérales. De plus, la présence de ce paramètre pourrait être pris comme une indication que la syntaxe d'échappement d'une chaîne (E'...') est acceptée.

Bien que le pointeur renvoyé est déclaré const, il pointe en fait vers un stockage mutable associé avec la structure PGconn. Il est déconseillé de supposer que le pointeur restera valide pour toutes les requêtes.

PQprotocolVersion

Interroge le protocole interface/moteur lors de son utilisation.

                  int PQprotocolVersion(const PGconn *conn);
       

Les applications souhaitent 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). La version du protocole ne changera pas après la fin du lancement de la connexion mais cela pourrait être changé théoriquement avec une réinitialisation de la connexion. Le protocole 3.0 sera 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).

PQserverVersion

Renvoie un entier représentant la version du moteur.

                  int PQserverVersion(const PGconn *conn);

Les applications pourraient utiliser ceci pour déterminer la version du serveur de la base de données auquel ils sont connectés. Le numéro est formé en convertissant les nombres majeur, mineur et de révision en un nombre à deux chiffres décimaux et en leur assemblant. Par exemple, la version 8.1.5 sera renvoyée en tant que 80105 et la version 8.2 sera renvoyée en tant que 80200 (les zéros au début ne sont pas affichés). Zéro est renvoyée si la connexion est mauvaise.

PQerrorMessage

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 initialiseront un message pour PQerrorMessage en cas d'échec. Notez que, par la convention libpq, un résultat non vide de PQerrorMessage peut être sur plusieurs lignes et contiendra un retour chariot à la fin. L'appelant ne devrait pas libérer directement le résultat. Il sera libéré quand la poignée PGconn associée est passée à PQfinish. Vous ne devriez pas supposer que la chaîne résultante reste identique suite à toutes les opérations sur la structure PGconn.

PQsocket

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

int PQsocket(const PGconn *conn);
       
PQbackendPID

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 incluent 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 !

PQconnectionNeedsPassword

Renvoie true (1) si la méthode d'authentification de la connexion nécessite un mot de passe, mais qu'aucun n'est disponible. Renvoie false (0) sinon.

        int PQconnectionNeedsPassword(const PGconn *conn);
       

Cette fonction peut être utilisée après une tentative échouée de connexion pour décider de la demande d'un utilisateur pour un mot de passe.

PQconnectionUsedPassword

Renvoie true (1) si la méthode d'authentification de la connexion a utilisé un mot de passe. Renvoie false (0) sinon.

        int PQconnectionUsedPassword(const PGconn *conn);
       

Cette fonction peut être utilisée après une connexion, réussie ou en échec, pour détecter si le serveur demande un mot de passe.

Les fonctions ci-dessous renvoient des informations relatives à SSL. Cette information ne change généralement pas après qu'une connexion soit établie.

PQsslInUse

Renvoie true (1) si la connexion utilise SSL, false (0) dans le cas contraire.

int PQsslInUse(const PGconn *conn);
PQsslAttribute

Renvoie des informations relatives à SSL à propos de la connexion.

const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);

La liste des attributs disponibles varie en fonction de la bibliothèque SSL utilisée, et du type de la connexion. Si un attribut n'est pas disponible, renvoie NULL.

Les attributs suivants sont communément disponibles :

library

Nom de l'implémentation SSL utilisée. (À ce jour seul "OpenSSL" est implémenté)

protocol

SSL/TLS version utilisée. Les valeurs courantes sont "SSLv2", "SSLv3", "TLSv1", "TLSv1.1" et "TLSv1.2", mais une implémentation peut renvoyer d'autres chaînes si d'autres protocoles sont utilisés.

key_bits

Nombre de bits clefs utilisés par l'algorithme de chiffrement.

cipher

Le nom raccourci de la suite cryptographique utilisée, par exemple "DHE-RSA-DES-CBC3-SHA". Les noms sont spécifiques à chaque implémentation.

compression

Si la compression SSL est utilisée, renvoie le nom de l'algorithme de compression, ou "on" si la compression est utilisée mais que l'algorithme est inconnu. Si la compression n'est pas utilisée, renvoie "off".

PQsslAttributeNames

Renvoie un tableau des attributs SSL disponibles. Le tableau est terminé par un pointeur NULL.

const char * const * PQsslAttributeNames(const PGconn *conn);
PQsslStruct

Renvoie un pointeur sur un objet SSL qui est dépendant de l'implémentation et qui décrit la connexion.

void *PQsslStruct(const PGconn *conn, const char *struct_name);

La ou les structures disponibles dépendent de l'implémentation SSL utilisée. Pour OpenSSL, il y a une structure, disponible sous le nom "OpenSSL", qui renvoie un pointeur sur la structure OpenSSL SSL. Un exemple de code utilisant cette fonction pourrait être :

 #include <libpq-fe.h>
 #include <openssl/ssl.h>

 ...

     SSL *ssl;

     dbconn = PQconnectdb(...);
     ...

     ssl = PQsslStruct(dbconn, "OpenSSL");
     if (ssl)
     {
         /* utilisez les fonctions OpenSSL pour accéder à ssl */
     }
 

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

PQgetssl

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

void *PQgetssl(const PGconn *conn);

Cette fonction est équivalente à PQsslStruct(conn, "OpenSSL"). Elle ne devrait pas être utilisée dans les nouvelles applications, car la structure renvoyée est spécifique à OpenSSL et ne sera pas disponible si une autre implémentation SSL est utilisée. Pour vérifier si une connexion utilise SSL, appeler à la place la fonction PQsslInUse, et pour plus de détails à propos de la connexion, utilisez PQsslAttribute.