31.11. Fonctions diverses

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û à l'allocation de la mémoire dans une DLL et la relâcher dans l'application fonctionne seulement 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.

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 supplémentaires.

Prépare la forme chiffrée du mot de passe PostgreSQL™.

char * PQencryptPassword(const char *passwd, const char *user);

Cette fonction est utilisée par les applications clientes qui souhaitent envoyées 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 en clair en une forme chiffrée avant de l'envoyer. Les arguments sont le mot de passe en clair et le nom SQL de l'utilisateur. La valeur renvoyée est une chaîne allouée par malloc ou NULL s'il ne reste plus de mémoire. L'appelant assume que la chaîne ne contient aucun caractère spécial qui nécessiterait un échappement. Utilisez PQfreemem pour libérer le résultat une fois terminé.

Construit un objet PGresult vide avec la 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 eux-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 actuel 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.

Déclenche un événement PGEVT_RESULTCREATE (voir Section 31.13, « Système d'événements ») pour chaque procédure d'événement enregistré dans l'objet PGresult. Renvoit autre chose que zéro en cas de succès, zéro si la procédure 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'utiliseront 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.

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 dans que 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 dans la source. (Néanmoins, il copie la chaîne de statut de commande.) L'argument flags détermine le reste à copier. 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.)

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.

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 au 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.

Alloue un stockage supplémentaire pour un objet PGresult.

       void *PQresultAlloc(PGresult *res, size_t nBytes);
      

Toute mémoire allouée avec cette fonction est libérée quand res est effacée. 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.

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 ou si la sortie hex du type bytea ajoutée par PostgreSQL 9.0 est supportée.

Le nombre est formé par conversion des numéros majeur, mineur et de révision en nombre à deux chiffres et en les concaténant les uns aux autres. Par exemple, la version 9.1 sera renvoyée en tant que 90100, alors que la version 9.1.2 sera renvoyée en tant que 90102 (Les zéros en début de chiffres ne sont pas affichées).

Note

Cette fonction apparaît en version 9.1 de PostgreSQL™, donc elle ne peut pas être utilisée pour détecter des fonctionnalités des versions précédentes car l'édition de lien créera une dépendance sur la version 9.1.