Ces fonctions sont utilisées pour interroger le statut d'un objet de connexion existant.
Les développeurs d'application libpq devraient être
attentif à maintenir l'abstraction PGconn
.
Utilisez les fonctions d'accès décrites ci-dessous pour obtenir le
contenu de PGconn
.
Référencer 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 la
connexion. Si une chaîne de connexion multi-hôtes est utilisée, les valeurs
de PQhost
, PQport
et PQpass
peuvent changer si une nouvelle connexion est
établie en utilisant le même objet PGconn
. Les
autres valeurs sont figées 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);
PQpass
retournera soit le mot de passe spécifié dans
les paramètres de connexion, soit, s'il n'y en avait pas, le mot
de passe obtenu depuis le fichier de mots de
passe. Dans ce dernier cas, si plusieurs hôtes étaient spécifiés
dans les paramètres de connexion, il n'est pas possible de se fier au
résultat de PQpass
jusqu'à l'établissement de la
connexion. Le statut de la connexion peut être vérifié avec la
fonction PQstatus
.
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 si la
connexion est réalisée via un socket Unix. (Le cas du chemin se distingue
par le fait que ce sera toujours un chemin absolu commençant par
/
.)
char *PQhost(const PGconn *conn);
Si les paramètres de connexion host
and
hostaddr
sont tous les deux précisés,
alors PQhost
retournera
host
. Si seul hostaddr
a été
spécifié, c'est cela qui est retourné. Si plusieurs hôtes sont spécifiés
dans les paramètres de connexion, PQhost
retourne
l'hôte à qui l'on s'est effectivement connecté.
PQhost
retourne NULL
si l'argument
conn
est NULL
.
Sinon, s'il y a une erreur en déterminant l'host
(peut-être que la connexion n'a pas été complètement établie ou qu'il y
a eu une erreur), il retourne une chaîne vide.
Si plusieurs hôtes ont été spécifiés dans les paramètres de connexion,
il n'est pas possible de se baser sur le résultat de
PQhost
avant l'établissement de la connexion.
Le statut de la connexion peut être vérifié avec la fonction
PQstatus
.
PQhostaddr
Renvoie l'adresse IP du serveur de la connexion active.
Ca peut être l'adresse résultant de la résolution d'un nom d'hôte,
ou une adresse IP fournie par le paramètre hostaddr
.
char *PQhostaddr(const PGconn *conn);
PQhostaddr
renvoie NULL
si
l'argument conn
est NULL
.
Sinon, si une erreur survient en produisant l'information sur
l'hôte (peut-être parce que la connexion n'a pas été complètement
établie ou qu'elle a subi une erreur), renvoie une chaîne vide.
PQport
Renvoie le numéro de port utilisé pour la connexion active.
char *PQport(const PGconn *conn);
Si de multiples ports étaient spécifiés dans les paramètres de
connexion, PQport
renvoie le port auquel on est
effectivement connecté.
PQport
retourne NULL
si l'argument
conn
est NULL
.
Sinon, s'il y a une erreur en déterminant le port
(peut-être que la connexion n'a pas été complètement établie ou qu'il y
a eu une erreur), il retourne une chaîne vide.
Si plusieurs ports ont été spécifiés dans les paramètres de connexion,
il n'est pas possible de se baser sur le résultat de
PQport
avant l'établissement de la connexion.
Le statut de la connexion peut être vérifié avec la fonction
PQstatus
.
PQtty
Cette fonction ne fait plus rien, mais elle reste disponible pour des
raisons de compatibilité ascendante. La fonction renvoie toujours une
chaîne vide ou NULL
si l'argument
conn
vaut NULL
.
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 des données de statut qui peuvent changer
suite à des opérations sur l'objet PGconn
.
PQstatus
Renvoie l'état de la connexion.
ConnStatusType PQstatus(const PGconn *conn);
Le statut peut prendre un certain nombre de valeurs. Néanmoins,
deux seulement ne concernent pas les procédures de connexion
asynchrone : CONNECTION_OK
et
CONNECTION_BAD
. Une bonne connexion à la base de
données a l'état CONNECTION_OK
. Une tentative de
connexion ayant échoué est signalée par le statut
CONNECTION_BAD
. D'habitude, un état OK le restera
jusqu'à PQfinish
mais un échec dans les communications
peut résulter en un statut changeant prématurément en
CONNECTION_BAD
. Dans ce cas, l'application peut
essayer de rattraper la situation en appelant PQreset
.
Voir l'entrée de PQconnectStartParams
, PQconnectStart
et de
PQconnectPoll
à propos des 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 de transaction
valide) ou PQTRANS_INERROR
(inactif, dans un bloc de
transaction échoué). PQTRANS_UNKNOWN
est rapporté si la
connexion est mauvaise. PQTRANS_ACTIVE
n'est rapporté
que si une requête a été envoyée au serveur et n'est pas encore terminée.
PQparameterStatus
Recherche la valeur en cours d'un paramètre du serveur.
const char *PQparameterStatus(const PGconn *conn, const char *paramName);
Certaines valeurs de paramètres sont rapportées par le serveur automatiquement ou
lorsque leur valeurs changent. PQparameterStatus
peut être utilisé
pour interroger ces paramètres. Il renvoie la valeur en cours d'un
paramètre s'il est connu et NULL
si le paramètre est inconnu.
Les paramètres renvoyées par la version actuelle incluent
server_version
,
server_encoding
,
client_encoding
,
application_name
,
default_transaction_read_only
,
in_hot_standby
,
is_superuser
,
session_authorization
,
datestyle
,
IntervalStyle
,
TimeZone
,
integer_datetimes
et
standard_conforming_strings
.
(server_encoding
, TimeZone
et
integer_datetimes
n'étaient pas renvoyés dans les
versions antérieures à la 8.0 ;
standard_conforming_strings
n'était pas renvoyé dans
les versions antérieures à la 8.1 ;
IntervalStyle
n'était pas renvoyé dans les versions
antérieures à la 8.4 ;
application_name
n'était pas renvoyé dans les
versions antérieures à la 9.0 ;
default_transaction_read_only
et
in_hot_standby
n'étaient pas renvoyés dans les
versions antérieures à la 14.).
Notez que
server_version
,
server_encoding
et
integer_datetimes
ne peuvent pas changer après le lancement du serveur.
Si aucune valeur n'est indiquée pour standard_conforming_strings
,
les applications peuvent considérer 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 peut être pris
comme une indication que la syntaxe d'échappement de chaîne
(E'...'
) est acceptée.
Bien que le pointeur renvoyé est déclaré const
, il pointe en fait
vers un stockage mutable associé à 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 peuvent utiliser ceci pour déterminer si certaines fonctionnalités sont supportées. Actuellement, les seules valeurs possible sont 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 il pourrait théoriquement changer lors d'une réinitialisation de la connexion. Le protocole 3.0 est supporté par les versions 7.4 et suivantes de PostgreSQL.
PQserverVersion
Renvoie un entier représentant la version du moteur.
int PQserverVersion(const PGconn *conn);
Les applications peuvent utiliser cette fonction pour déterminer la version du serveur de bases de données où ils sont connectés Le résultat est obtenu en multipliant le numéro de version majeure de la bibliothèque par 10000 et en ajoutant le numéro de version mineure. Par exemple, la version 10.1 renverra 100001, et la version 11.0 renverra 110000. Zéro est renvoyé si la connexion est mauvaise.
Avant la version majeure 10, PostgreSQL
utilisait des numéros de version en trois parties, pour lesquelles les
deux premières parties représentaient la version majeure. Pour ces
versions, PQlibVersion
utilise deux chiffres pour
chaque partie. Par exemple, la version 9.1.5 renverra 90105, et la
version 9.2.0 renverra 90200.
De ce fait, pour déterminer la compatibilité de certaines
fonctionnalités, les applications devrait diviser le résultat de
PQserverVersion
par 100, et non pas par 10000,
pour déterminer le numéro de version majeure logique. Dans toutes les
versions, seuls les deux derniers chiffres diffèrent entre des versions
mineures (versions correctives).
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 convention dans libpq, un résultat
non vide de PQerrorMessage
peut courir sur plusieurs lignes
et finira par un retour chariot.
L'appelant ne devrait pas libérer directement le
résultat. Il sera libéré quand le pointeur PGconn
associé
sera passé à PQfinish
. La chaîne résultante n'est pas
supposée rester la même pendant 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 du fonctionnement habituel, mais pourrait changer lors de la mise en place de la connexion 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 processus backend 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 un échec de connexion pour décider s'il faut demander un mot de passe à l'utilisateur.
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. Renvoie NULL si la connexion n'utilise pas SSL ou si le nom de l'attribut spécifié n'est pas défini pour la bibliothèque utilisée.
Les attributs suivants sont communément disponibles :
library
Nom de l'implémentation SSL utilisée. (À ce jour seul
"OpenSSL"
est implémenté)
protocol
Version de SSL/TLS utilisée. Les valeurs courantes sont
"TLSv1"
, "TLSv1.1"
and "TLSv1.2"
, mais une implémentation
peut renvoyer d'autres chaînes si d'autres protocoles
sont utilisés.
key_bits
Nombre de bits de la clef utilisée 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
Renvoie "on" si la compression SSL est utilisée, sinon renvoie "off".
Comme cas particulier, l'attribut library
peut être
requêté sans connexion en passant NULL à l'argument
conn
. Le résultat sera le nom de la bibliothèque SSL
par défaut ou NULL si libpq a été compilé sans
le support SSL. (Avant PostgreSQL version 15,
passer NULL pour l'argument conn
résultait toujours en
un NULL. Les programmes clients qui ont besoin de différencier entrer
les implémentations nouvelle et ancienne dans ce cas peuvent vérifier la
macro LIBPQ_HAS_SSL_LIBRARY_DETECTION
.)
PQsslAttributeNames
Renvoie un tableau des noms d'attribut 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. Renvoie NULL si la connexion n'est pas chiffrée ou si le type demandé d'un objet n'est pas disponible à partir de l'implémentation SSL de la connexion.
void *PQsslStruct(const PGconn *conn, const char *struct_name);
Là où 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 SSL
d'OpenSSL. 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, appelez plutôt PQsslInUse
, et, pour plus de détails à propos de la
connexion, utilisez PQsslAttribute
.