Comme toujours, certaines fonctions ne sont pas catégorisables.
PQfreemem
#Libère la mémoire allouée par libpq.
void PQfreemem(void *ptr);
Libère la mémoire allouée par libpq,
particulièrement PQescapeByteaConn
,
PQescapeBytea
,
PQunescapeBytea
,
et PQnotifies
. Il est particulièrement important
que cette fonction, plutôt que free()
, soit utilisée
sur Microsoft Windows. Ceci est dû au fait qu'allouer de la mémoire dans une
DLL et la relâcher dans l'application ne marche que si les drapeaux
multi-thread/mon-thread, release/debug et static/dynamic sont les mêmes
pour la DLL et l'application. Sur les plateformes autres que Microsoft
Windows, cette fonction est identique à la fonction
free()
de la bibliothèque standard.
PQconninfoFree
#
Libère les structures de données allouées par
PQconndefaults
ou PQconninfoParse
.
void PQconninfoFree(PQconninfoOption *connOptions);
Si l'argument est un pointeur NULL
, aucune opération
n'est réalisée.
Un simple appel à PQfreemem
ne suffira pas car le
tableau contient des références à des chaînes complémentaires.
PQencryptPasswordConn
#Prépare la forme chiffrée du mot de passe PostgreSQL.
char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm);
Cette fonction est utilisée par les applications clientes qui souhaitent envoyer
des commandes comme ALTER USER joe PASSWORD 'passe'
.
Une bonne pratique est de ne pas envoyer le mot de passe en clair dans une
telle commande car le mot de passe serait exposé dans les journaux, les affichages
d'activité et ainsi de suite. À la place, utilisez cette fonction pour convertir
le mot de passe sous forme chiffrée avant de l'envoyer.
Les arguments passwd
et
user
sont le mot de passe en clair et le nom
SQL de l'utilisateur correspondant.
algorithm
spécifie l'algorithme de chiffrement à
utiliser pour chiffrer le mot de passe. Pour le moment, les algorithmes
supportés sont md5
et scram-sha-256
(on
et off
sont également acceptés
comme des alias pour md5
, pour compatibilité avec les
versions des anciens serveurs). Veuillez noter que le support de
scram-sha-256
a été introduit dans la version 10 de
PostgreSQL, et ne fonctionnera pas
correctement avec des versions de serveur plus ancienne. Si
algorithm
est NULL
, cette
fonction demandera au serveur la valeur actuelle du réglage
password_encryption. Cela peut être bloquant, et
échouera si la transaction courante est annulée ou si la connexion est
occupée à effectuer une autre requête. Si vous souhaitez utiliser
l'algorithme par défaut du serveur mais que vous voulez éviter un
blocage, vérifiez vous-même password_encryption
avant
d'appeler PQencryptPasswordConn
, et fournissez cette
valeur pour algorithm
.
La valeur retournée est une chaîne allouée par
malloc
. L'appelant peut partir du principe que la
chaîne ne contient pas de caractères spéciaux qui nécessiteraient un
échappement. Utilisez PQfreemem
pour libérer le
résultat quand vous avez fini de l'utiliser. En cas d'erreur,
NULL
est retourné, et un message d'erreur adéquat est
stocké dans l'objet de connexion.
PQencryptPassword
#Prépare la version chiffrée en md5 du mot de passe PostgreSQL.
char *PQencryptPassword(const char *passwd, const char *user);
PQencryptPassword
est une version ancienne et
obsolète de PQencryptPasswordConn
. La différence
est que PQencryptPassword
ne nécessite pas d'objet
de connexion, et que l'algorithme de chiffrement utilisé est toujours
md5
.
PQmakeEmptyPGresult
#
Construit un objet PGresult
vide avec le statut
indiqué.
PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
C'est une fonction interne de la libpq pour
allouer et initialiser un objet PGresult
vide.
Cette fonction renvoit NULL si la mémoire n'a pas pu être allouée. Elle
est exportée car certaines applications trouveront utiles de générer
elles-mêmes des objets de résultat (tout particulièrement ceux avec des
statuts d'erreur). Si conn
n'est pas NULL
et que
status
indique une erreur, le message d'erreur
courant de la connexion indiquée est copié dans
PGresult
. De plus, si
conn
n'est pas NULL, toute procédure d'événement
enregistrée dans la connexion est copiée dans le
PGresult
. (Elles n'obtiennent pas d'appels
PGEVT_RESULTCREATE
, mais jetez un œil à
PQfireResultCreateEvents
.)
Notez que PQclear
devra être appelé sur l'objet,
comme pour un PGresult
renvoyé par
libpq lui-même.
PQfireResultCreateEvents
#
Déclenche un événement PGEVT_RESULTCREATE
(voir Section 34.14) pour chaque procédure d'événement enregistrée
dans l'objet PGresult
. Renvoit autre chose que
zéro en cas de succès, zéro si une des procédures d'événement échoue.
int PQfireResultCreateEvents(PGconn *conn, PGresult *res);
L'argument conn
est passé aux procédures d'événement
mais n'est pas utilisé directement. Il peut être NULL
si les procédures de l'événement ne l'utilisent pas.
Les procédures d'événements qui ont déjà reçu un événement
PGEVT_RESULTCREATE
ou
PGEVT_RESULTCOPY
pour cet objet ne sont pas déclenchées
de nouveau.
La raison principale pour séparer cette fonction de
PQmakeEmptyPGresult
est qu'il est souvent approprié
de créer un PGresult
et de le remplir avec des
données avant d'appeler les procédures d'événement.
PQcopyResult
#
Fait une copie de l'objet PGresult
. La copie
n'est liée en aucune façon au résultat source et
PQclear
doit être appelée quand la copie n'est
plus nécessaire. Si la fonction échoue, NULL
est renvoyé.
PGresult *PQcopyResult(const PGresult *src, int flags);
Cela n'a pas pour but de faire une copie exacte. Le résultat renvoyé a
toujours le statut PGRES_TUPLES_OK
, et ne copie aucun
message d'erreur de la source. (Néanmoins, elle copie la chaîne de statut
de commande.) L'argument flags
détermine ce qui
est copié. C'est un OR bit à bit de plusieurs drapeaux.
PG_COPYRES_ATTRS
indique la copie des attributs du
résultat source (définition des colonnes).
PG_COPYRES_TUPLES
indique la copie des lignes du
résultat source. (Cela implique de copier aussi les attributs.)
PG_COPYRES_NOTICEHOOKS
indique la copie des
gestionnaires de notification du résultat source.
PG_COPYRES_EVENTS
indique la copie des événements du
résultat source. (Mais toute instance de données associée avec la source
n'est pas copiée.)
Les procédures événement reçoivent les événements PGEVT_RESULTCOPY
.
PQsetResultAttrs
#
Initialise les attributs d'un objet PGresult
.
int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);
Les attDescs
fournis sont copiés dans le résultat.
Si le pointeur attDescs
est NULL
ou si
numAttributes
est inférieur à 1, la requête est
ignorée et la fonction réussit. Si res
contient
déjà les attributs, la fonction échouera. Si la fonction échoue, la valeur
de retour est zéro. Si la fonction réussit, la valeur de retour est
différente de zéro.
PQsetvalue
#
Initialise la valeur d'un champ d'une ligne d'un objet
PGresult
.
int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);
La fonction fera automatiquement grossir le tableau de lignes internes des
résultats, si nécessaire. Néanmoins, l'argument
tup_num
doit être inférieur ou égal à
PQntuples
, ceci signifiant que la fonction peut
seulement faire grossir le tableau des lignes une ligne à la fois. Mais
tout champ d'une ligne existante peut être modifié dans n'importe quel
ordre. Si une valeur à field_num
existe déjà, elle
sera écrasée. Si len
vaut 1 ou
si value
est NULL
, la valeur
du champ sera configurée à la valeur SQL NULL
.
value
est copié dans le stockage privé du résultat,
donc n'est plus nécessaire après le retour de la fonction. Si la fonction échoue,
la valeur de retour est zéro. Dans le cas contraire, elle a une valeur
différente de zéro.
PQresultAlloc
#
Alloue un stockage supplémentaire pour un objet
PGresult
.
void *PQresultAlloc(PGresult *res, size_t nBytes);
Toute mémoire allouée avec cette fonction sera libérée quand
res
sera effacé. Si la fonction échoue, la valeur
de retour vaut NULL
. Le résultat est garanti d'être
correctement aligné pour tout type de données, comme pour un
malloc
.
PQresultMemorySize
#
Renvoie le nombre d'octets alloués pour un objet
PGresult
.
size_t PQresultMemorySize(const PGresult *res);
La valeur est la somme de tous les appels malloc
associés avec l'objet PGresult
, c'est-à-dire
tout l'espace qui peut être libéré par PQclear
.
Cette information est utile pour gérer la consommation mémoire.
PQlibVersion
#Renvoie la version de libpq en cours d'utilisation.
int PQlibVersion(void);
Le résultat de cette fonction peut être utilisé pour déterminer,
à l'exécution, si certaines fonctionnalités spécifiques sont
disponibles dans la version chargée de libpq. Par exemple, cette
fonction peut être utilisée pour déterminer les options de
connexions disponibles pour PQconnectdb
.
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.
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 devraient diviser le résultat de
PQlibVersion
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).
Cette fonction apparaît dans PostgreSQL 9.1, donc elle ne peut pas être utilisée pour détecter des fonctionnalités des versions précédentes car l'appeler créera une dépendance sur la version 9.1 et les versions ultérieures.