Documentation PostgreSQL 14.22 » Interfaces client » libpq -- Bibliothèque C » Fonctions diverses

Précédent | Niveau supérieur | Suivant
34.11. Fonctions de contrôle | Sommaire | 34.13. Traitement des messages

## 34.12. Fonctions diverses

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

  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 renvoie 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`. Renvoie 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.)

`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).

  ### Note

  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.