Établit une nouvelle connexion au serveur de base de données.

PGconn *PQconnectdbParams(const char * const *keywords,
                          const char * const *values,
                          int expand_dbname);
       

Cette fonction ouvre une nouvelle connexion à la base de données en utilisant les paramètres à partir des deux tableaux terminés par un NULL. Le premier, keywords, est défini comme un tableau de chaînes, chacune étant un mot-clé. Le second, values, donne la valeur pour chaque mot-clé. Contrairement à PQsetdbLogin ci-dessous, l'ensemble des paramètres peut être étendu sans changer la signature de la fonction donc son utilisation (ou ses versions non bloquantes, à savoir PQconnectStartParams et PQconnectPoll) est recommendée pour les nouvelles applications.

Les mots clés actuellement reconnus sont listés dans Section 33.1.2.

Les tableaux fournis peuvent être vides pour utiliser tous les paramètres par défaut ou peuvent contenir une ou plusieurs configurations. Elles doivent correspondre en longueur. Le traitement s'arrêtera à la première entrée NULL dans le tableau keywords. De plus, si l'entrée values associée à une entrée keywords non NULL est NULL ou une chaîne vide, cette entrée est ignorée et le traitement continue avec la prochaine paire d'entrées des tableaux.

Quand expand_dbname est différent de zéro, la valeur pour le premier mot-clé dbname est testé pour vérifier s'il s'agit d'une chaîne de connexion. Dans ce cas, elle sera « éclatée » dans les paramètres individuels de connexion. La valeur est considérée être une chaîne de connexion, plutôt qu'un nom de base, si elle contient un signe égal (=) ou si elle commence avec un désignateur de schéma URI. (Vous trouverez plus de détails sur les formats de chaîne de connexion dans Section 33.1.1.) Seule la première occurence de dbname est traitée de cette façon ; tout paramètre dbname supplémentaire est traité comme un simple nom de base.

En général, les tableaux de paramètres sont traités du début à la fin. Si un mot clé est répété, la dernière valeur (non NULL ou vide) est utilisée. Cette règle s'applique en particulier quand un mot clé trouvé dans la chaîne de connexion est en conflit avec un mot clé apparaissant dans le tableau keywords. De ce fait, le développeur peut déterminer si les entrées du tableau peuvent surcharger ou être surchargées par des valeurs prises dans la chaîne de connexion. Les entrées du tableau apparaissant avant une entrée dbname éclatée peuvent être surchargées par les champs de la chaîne de connexion et, à leur tour,ces champs peuvent être surchargés par des entrées du tableau apparaissant après dbname (mais, encore une fois, seulement si ces entrées fournissent des valeurs non vides).

Après avoir traité toutes les entrées de tableau et toute chaîne de connexion éclatée, tous les paramètres de connexion restants non configurés sont remplis avec leur valeurs par défaut. Si une variable d'environnement d'un paramètre non configuré (voir Section 33.14) est configuré, sa valeur est utilisée. Si la variable denvironnement n'est pas configurée, alors la valeur par défaut interne du paramètre est utilisée.

Établit une nouvelle connexion à un serveur de bases de données.

        PGconn *PQconnectdb(const char *conninfo);
       

Cette fonction ouvre une nouvelle connexion à la base de données en utilisant les paramètres pris à partir de la chaîne conninfo.

La chaîne passée peut être vide pour utiliser tous les paramètres par défaut ou elle peut contenir un ou plusieurs paramètres, séparés par des espaces blancs. Elle peut aussi contenir une URI. Voir Section 33.1.1 pour les détails.

Crée une nouvelle connexion sur le serveur de bases de données.

PGconn *PQsetdbLogin(const char *pghost,
                     const char *pgport,
                     const char *pgoptions,
                     const char *pgtty,
                     const char *dbName,
                     const char *login,
                     const char *pwd);
       

C'est le prédécesseur de PQconnectdb avec un ensemble fixe de paramètres. Cette fonction a les mêmes fonctionnalités sauf que les paramètres manquants seront toujours initialisés avec leur valeurs par défaut. Écrire NULL ou une chaîne vide pour un de ces paramètres fixes dont vous souhaitez utiliser la valeur par défaut.

Si dbName contient un signe = ou a un préfixe URI de connexion valide, il est pris pour une chaîne conninfo exactement de la même façon que si elle était passée à PQconnectdb, et le reste des paramètres est ensuite appliqué comme spécifié dans PQconnectdbParams.

Crée une nouvelle connexion sur le serveur de bases de données.

PGconn *PQsetdb(char *pghost,
                char *pgport,
                char *pgoptions,
                char *pgtty,
                char *dbName);
       

C'est une macro faisant appel à PQsetdbLogin avec des pointeurs nuls pour les paramètres login et pwd. Elle est fournie pour une compatibilité ascendante des très vieux programmes.

Crée une connexion au serveur de bases de données d'une façon non bloquante.

PGconn *PQconnectStartParams(const char * const *keywords,
                             const char * const *values,
                              int expand_dbname);

        PGconn *PQconnectStart(const char *conninfo);

        PostgresPollingStatusType PQconnectPoll(PGconn *conn);
       

Ces trois fonctions sont utilisées pour ouvrir une connexion au serveur de bases de données d'une façon telle que le thread de votre application n'est pas bloqué sur les entrées/sorties distantes en demandant la connexion. Le but de cette approche est que l'attente de la fin des entrées/sorties peut se faire dans la boucle principale de l'application plutôt qu'à l'intérieur de PQconnectdbParams ou PQconnectdb, et donc l'application peut gérer des opérations en parallèle à d'autres activités.

Avec PQconnectStartParams, la connexion à la base de données est faite en utilisant les paramètres à partir des tableaux keywords et values, et contrôlée par expand_dbname, comme décrit dans Section 33.1.2.

Avec PQconnectStart, la connexion à la base de données est faite en utilisant les paramètres provenant de la chaîne conninfo comme décrit ci-dessus pour PQconnectdb.

Ni PQconnectStartParams ni PQconnectStart ni PQconnectPoll ne bloqueront, aussi longtemps qu'un certain nombre de restrictions est respecté :

Pour commencer une demande de connexion non bloquante, appelez PQconnectStart ou PQconnectStartParams. Si le résultat est null, alors libpq a été incapable d'allouer une nouvelle structure PGconn. Sinon, un pointeur valide vers une structure PGconn est renvoyé (bien qu'il ne représente pas encore une connexion valide vers la base de données). Ensuite, appelez PQstatus(conn). Si le résultat vaut CONNECTION_BAD, la tentative de connexion a déjà échoué, généralement à cause de paramètres de connexion invalides.

Si PQconnectStart ou PQconnectStartParams réussit, la prochaine étape est d'appeler souvent libpq de façon à ce qu'il continue la séquence de connexion. Utilisez PQsocket(conn) pour obtenir le descripteur de socket sous la connexion à la base de données. (Attention : ne supposez pas que le socket reste le même auprès plusieurs appels à PQconnectPoll.) Du coup, une boucle : si le dernier retour de PQconnectPoll(conn) est PGRES_POLLING_READING, attendez que la socket soit prête pour lire (comme indiqué par select(), poll() ou une fonction système similaire). Puis, appelez de nouveau PQconnectPoll(conn). En revanche, si le dernier retour de PQconnectPoll(conn) est PGRES_POLLING_WRITING, attendez que la socket soit prête pour écrire, puis appelez de nouveau PQconnectPoll(conn). Sur la première itération, si vous devez encore appeler PQconnectPoll, continuez comme s'il avait renvoyé PGRES_POLLING_WRITING. Continuez cette boucle jusqu'à ce que PQconnectPoll(conn) renvoie PGRES_POLLING_FAILED, indiquant que la procédure de connexion a échoué ou PGRES_POLLING_OK, indiquant le succès de la procédure de connexion.

À tout moment pendant la connexion, le statut de cette connexion pourrait être vérifié en appelant PQstatus. Si le résultat est CONNECTION_BAD, alors la procédure de connexion a échoué ; si, au contraire, elle renvoie CONNECTION_OK, alors la connexion est prête. Ces deux états sont détectables à partir de la valeur de retour de PQconnectPoll, décrite ci-dessus. D'autres états pourraient survenir lors (et seulement dans ce cas) d'une procédure de connexion asynchrone. Ils indiquent l'état actuel de la procédure de connexion et pourraient être utile pour fournir un retour à l'utilisateur. Ces statuts sont :

Notez que, bien que ces constantes resteront (pour maintenir une compatibilité), une application ne devrait jamais se baser sur l'apparition de ces états dans un ordre particulier, ou leur survenance tout court, ou sur le fait que le statut fait partie de ces valeurs documentées. Une application pourrait faire quelque chose comme ça :

switch(PQstatus(conn))
{
    case CONNECTION_STARTED:
        feedback = "Connexion en cours...";
        break;

    case CONNECTION_MADE:
        feedback = "Connecté au serveur...";
        break;
.
.
.
    default:
        feedback = "Connexion...";
}
       

Le paramètre de connexion connect_timeout est ignoré lors de l'utilisation PQconnectPoll ; c'est de la responsabilité de l'application de décider quand une période de temps excessive s'est écoulée. Sinon, PQconnectStart suivi par une boucle PQconnectPoll est équivalent à PQconnectdb.

Notez que si PQconnectStart ou PQconnectStartParams renvoie un pointeur non nul, vous devez appeler PQfinish lorsque vous en avez terminé avec lui, pour supprimer la structure et tous les blocs mémoires qui lui sont associés. Ceci doit être fait même si la tentative de connexion échoue ou est abandonnée.

Renvoie les options de connexion par défaut.

PQconninfoOption *PQconndefaults(void);

typedef struct
{
    char   *keyword;   /* Mot clé de l'option */
    char   *envvar;    /* Nom de la variable d'environnement équivalente */
    char   *compiled;  /* Valeur par défaut interne */
    char   *val;       /* Valeur actuelle de l'option ou NULL */
    char   *label;     /* Label du champ pour le dialogue de connexion */
    char   *dispchar;  /* Indique comment afficher ce champ
                          dans un dialogue de connexion. Les valeurs sont :
                          ""        Affiche la valeur entrée sans modification
                          "*"       Champ de mot de passe - cache la valeur
                          "D"       Option de débogage - non affiché par défaut
                       */
    int     dispsize;  /* Taille du champ en caractère pour le dialogue */
} PQconninfoOption;
       

Renvoie un tableau d'options de connexion. Ceci pourrait être utilisé pour déterminer toutes les options possibles de PQconnectdb et leur valeurs par défaut. La valeur de retour pointe vers un tableau de structures PQconninfoOption qui se termine avec une entrée utilisant un pointeur nul pour keyword. Le pointeur null est renvoyé si la mémoire n'a pas pu être allouée. Notez que les valeurs par défaut actuelles (champs val) dépendront des variables d'environnement et d'autres contextes. Un fichier de service manquant ou non valide sera ignoré de manière silencieuse. Les demandeurs doivent traiter les données des options de connexion en lecture seule.

Après le traitement du tableau d'options, libérez-le en le passant à la fonction PQconninfoFree. Si cela n'est pas fait, un petit groupe de mémoire est perdu à chaque appel de PQconndefaults.

Renvoie les options de connexion utilisées par une connexion en cours.

       PQconninfoOption *PQconninfo(PGconn *conn);
       

Renvoie un tableau des options de connexion. Cette fonction peut être utilisée pour déterminer les valeurs de toutes les options de PQconnectdb qui ont été utilisées pour se connecter au serveur. La valeur renvoyée pointe vers un tableau de structures PQconninfoOption qui se termine avec une entrée possédant un pointeur keyword nul. Toutes les notes ci-dessus pour PQconndefaults s'appliquent aussi au résultat de PQconninfo.

Renvoit les options de connexions analysées d'après la chaîne de connexion fournie.

       PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);
       

Analyse une chaîne de connexion et renvoie les options résultantes dans un tableau ; renvoit NULL si un problème a été détecté avec la chaîne de connexion. Ceci peut être utilisé pour déterminer les options de PQconnectdb dans la chaîne de connexion fournie. La valeur de retour pointe vers un tableau de structures PQconninfoOption et termine avec une entrée ayant un pointeur keyword nul.

Toutes les options légales seront présentes dans le tableau en résultat mais le PQconninfoOption pour toute option absente de la chaîne de connexion aura sa valeur (val) configurée à NULL ; les valeurs par défaut ne sont pas utilisées.

Si errmsg n'est pas NULL, alors *errmsg est configuré à NULL en cas de succès et sinon à un message d'erreur (alloué via un appel à malloc) expliquant le problèm. (Il est aussi possible pour *errmsg d'être configuré à NULL et la fonction de renvoyer NULL ; cela indique un cas de mémoire épuisée.)

Après avoir traité le tableau des options, libérez-le en le passant à PQconninfoFree. Si ce n'est pas fait, de la mémoire sera perdu à chaque appel à PQconninfoParse. Réciproquement, si une erreur survient et que errmsg n'est pas NULL, assurez-vous de libérer la chaîne d'erreur en utilisant PQfreemem.

Ferme la connexion au serveur. Libère aussi la mémoire utilisée par l'objet PGconn.

void PQfinish(PGconn *conn);
       

Notez que même si la connexion au serveur a échoué (d'après l'indication de PQstatus), l'application devrait appeler PQfinish pour libérer la mémoire utilisée par l'objet PGconn. Le pointeur PGconn ne doit pas être encore utilisé après l'appel à PQfinish.

Réinitialise le canal de communication avec le serveur.

void PQreset(PGconn *conn);
       

Cette fonction fermera la connexion au serveur et tentera le rétablissement d'une nouvelle connexion au même serveur en utilisant tous les paramètres utilisés précédemment. Ceci pourrait être utile en cas de récupération après une perte de connexion.

Réinitialise le canal de communication avec le serveur d'une façon non bloquante.

       int PQresetStart(PGconn *conn);

       PostgresPollingStatusType PQresetPoll(PGconn *conn);
       

Ces fonctions fermeront la connexion au serveur et tenteront de rétablir une nouvelle connexion sur le même serveur, en utilisant tous les paramètres précédemment utilisés. Ceci peut être utile pour revenir à un état normal après une erreur si une connexion est perdue. Ces fonctions diffèrent de PQreset (ci-dessus) dans le fait qu'elles agissent d'une façon non bloquante. Ces fonctions souffrent des mêmes restrictions que PQconnectStartParams, PQconnectStart et PQconnectPoll.

Pour lancer une réinitialisation de la connexion, exécutez PQresetStart. Si cette fonction 0, la réinitialisation a échoué. Si elle renvoie 1, récupérez le résultat de la réinitialisation en utilisant PQresetPoll exactement de la même façon que vous auriez créé la connexion en utilisant PQconnectPoll.

PQpingParams renvoie le statut du serveur. Elle accepte les mêmes paramètres de connexion que ceux de la fonction PQconnectdbParams, décrite ci-dessus. Néanmoins, il n'est pas nécessaire de fournir les bons nom d'utilisateur, mot de passe, ou nom de base de données pour obtenir le statut du serveur. Néanmoins, si des valeurs incorrectes sont fournies, le serveur tracera une tentative échouée de connexion.

       PGPing PQpingParams(const char * const *keywords,
                    const char * const *values,
                    int expand_dbname);
       

La fonction renvoie une des valeurs suivantes :

PQping renvoie l'état du serveur. Elle accepte les mêmes paramètres de connexion que ceux de la fonction PQconnectdb, décrite ci-dessus. Néanmoins, il n'est pas nécessaire de fournir les bons nom d'utilisateur, mot de passe, ou nom de base de données pour obtenir le statut du serveur; toutefois, si des valeurs incorrectes sont fournies, le serveur tracera une tentative de connexion en échec.

       PGPing PQping(const char *conninfo);
       

Les valeurs de retour sont les mêmes que pour PQpingParams.