8.4 Interface C pour MySQL
8 Les interfaces pour MySQL
Manuel de Référence MySQL 4.1 : Version Française
. Types de données de l'API C
->Vue d'ensemble des fonctions de l'API C
. Description des fonctions de l'API C
. Description des fonctions threadées de C
. Description des fonctions C du serveur embarqué
. Questions courantes sur la librairie C
. Compiler les clients
. Comment faire un client MySQL threadé
. libmysqld, la librairie du serveur embarqué MySQL
|
8.4.2 Vue d'ensemble des fonctions de l'API C
Les fonctions disponibles dans l'API C sont listées ici et décrites en plus de détails
dans la section suivante.
Description des fonctions de l'interface C .
|
Fonction
|
Description
|
|
mysql_affected_rows()
|
Retourne le nombre de lignes changées/effacées/insérés par le dernier
UPDATE
,
DELETE
, ou
INSERT
. |
|
mysql_change_user()
|
Change l'utilisateur et la base de données pour une connexion ouverte. |
|
mysql_character_set_name()
|
Retourne le nom du jeu de caractère de la connexion. |
|
mysql_close()
|
Ferme une connexion au serveur. |
|
mysql_connect()
|
Connecte à un serveur MySQL. Cette fonction est désapprouvée; utilisez
mysql_real_connect()
à la place. |
|
mysql_create_db()
|
Crée une base de données. Cette fonction est désapprouvée, utilisez
plutôt la commande SQL
CREATE DATABASE
. |
|
mysql_data_seek()
|
Déplace le pointeur vers une ligne arbitraire dans le jeu de résultats de la requête. |
|
mysql_debug()
|
Effectue un
DBUG_PUSH
avec la chaîne donnée. |
|
mysql_drop_db()
|
Supprime une base de données. Cette fonction est désapprouvée, utilisez
plutôt la commande SQL
DROP DATABASE
. |
|
mysql_dump_debug_info()
|
Demande au serveur d'écrire les informations de débogage dans un fichier de log. |
|
mysql_eof()
|
Détermine si la dernière ligne du jeu de résultats a été lue ou non.
Cette fonction est désapprouvée, vous pouvez utiliser
mysql_errno()
ou
mysql_error()
à la place. |
|
mysql_errno()
|
Retourne le numéro de l'erreur de la fonction appelée en dernier. |
|
mysql_error()
|
Retourne le message d'erreur de la dernière fonction MySQL appelée. |
|
mysql_escape_string()
|
Protège une chaîne en échappant les caractères spéciaux. |
|
mysql_fetch_field()
|
Retourne le type du champ suivant dans la table. |
|
mysql_fetch_field_direct()
|
Retourne le type d'une colonne, étant donné un numéro de champ. |
|
mysql_fetch_fields()
|
Retourne un tableau avec toutes les structures de champs. |
|
mysql_fetch_lengths()
|
Retourne la longueur de toutes les colonnes dans la ligne suivante. |
|
mysql_fetch_row()
|
Récupère la ligne suivante dans le jeu de résultats. |
|
mysql_field_seek()
|
Place le curseur de colonne sur une colonne précise. |
|
mysql_field_count()
|
Retourne le nombre de colonnes dans le résultat pour la requête la plus récente. |
|
mysql_field_tell()
|
Retourne la position du curseur de champs utilisé pour le dernier appel à
mysql_fetch_field()
. |
|
mysql_free_result()
|
Libère la mémoire utilisée par un jeu de résultats. |
|
mysql_get_client_info()
|
Retourne la version du client. |
|
mysql_get_host_info()
|
Retourne une chaîne décrivant la connexion. |
|
mysql_get_proto_info()
|
Retourne la version du protocole utilisé par la connexion. |
|
mysql_get_server_info()
|
Retourne la version du serveur. |
|
mysql_info()
|
Retourne des informations à propos de la requête la plus récente. |
|
mysql_init()
|
Récupère ou initialise une structure
MYSQL
. |
|
mysql_insert_id()
|
Retourne l'identifié généré pour une colonne
AUTO_INCREMENT
par la dernière requête. |
|
mysql_kill()
|
Termine un processus donné. |
|
mysql_list_dbs()
|
Retourne les noms des bases de données répondant à une expression régulière simple. |
|
mysql_list_fields()
|
Retourne les noms des champs répondants à une expression régulière simple. |
|
mysql_list_processes()
|
Retourne une liste des processus courants du serveur. |
|
mysql_list_tables()
|
Retourne les noms des tables répondants à une expression régulière simple. |
|
mysql_num_fields()
|
Retourne le nombre de colonnes dans un jeu de résultats. |
|
mysql_num_rows()
|
Retourne le nombre de lignes dans le jeu de résultats. |
|
mysql_options()
|
Configure les options de connexion pour
mysql_connect()
. |
|
mysql_ping()
|
Vérifie si la connexion au serveur a toujours lieu. Reconnecte si besoin. |
|
mysql_query()
|
Exécute une requête SQL spécifée en tant que chaîne terminée par un
caractère nul. |
|
mysql_real_connect()
|
Connecte à un serveur MySQL. |
|
mysql_real_escape_string()
|
Protège les caractères spéciaux dans une chaîne utilisable dans une requête SQL, en prenant
en compte le jeu de caractères courant de la connexion. |
|
mysql_real_query()
|
Exécute une requête SQL spécifiée en tant que chaîne comptée. |
|
mysql_reload()
|
Demande au serveur de recharger la table des droits. |
|
mysql_row_seek()
|
Déplace le pointeur vers un ligne dans le jeu de résultats, en utilisant une valeur
retournée par
mysql_row_tell()
. |
|
mysql_row_tell()
|
Retourne la position du curseur de lignes. |
|
mysql_select_db()
|
Sélectionne une base de données. |
|
mysql_shutdown()
|
Termine le serveur de base de données. |
|
mysql_stat()
|
Retourne le statut du serveur dans une chaîne. |
|
mysql_store_result()
|
Récupère le jeu de résulats complet dans le client. |
|
mysql_thread_id()
|
Retourne l'identifiant du thread courant. |
|
mysql_thread_safe()
|
Retourne 1 si le client est compilé en tant que thread-safe. |
|
mysql_use_result()
|
Initialise une récupération ligne par ligne des résultats.
|
Pour vous connecter au serveur, appelez
mysql_init()
pour initialiser
un gestionnaire de connexion, puis appelez
mysql_real_connect()
avec
ce gestionnaire (avec d'autres informations tel que l'hôte, l'utilisateur et
le mot de passe). Lors de la connexion,
mysql_real_connect()
définit
l'option
reconnect
(quit fait partie de la structure MYSQL) à
1
.
Cette option indique, dans le cas où une requête ne peut être exécutée à cause
d'une perte de connexion, d'essayer de se reconnecter au serveur avant d'abandonner.
Lorsque vous n'avez plus besoin de la connexion, appelez
mysql_close()
pour la clore.
Tant qu'une connexion est active, le client envoi des requêtes SQL au serveur
à l'aide de
mysql_query()
ou
mysql_real_query()
. La différence entre
les deux est que
mysql_query()
s'attend à ce que la requête soit spécifiée
en tant que chaîne terminée par la chaîne nulle, tandis que
mysql_real_query()
attend une chaîne de longueur connue. Si la chaîne contient des données binaires
(incluant l'octet nul), vous devez utiliser
mysql_real_query()
.
Pour chaque requête non-sélective (par exemple,
INSERT
,
UPDATE
,
DELETE
), vous pouvez trouver combien de lignes ont été mises à jour (affectées)
en appelant
mysql_affected_rows()
.
Pour les requêtes
SELECT
, vous récupérez les lignes sélectionnées dans un
jeu de résultat. (Notez que quelques commandes ont le même comportement que
SELECT
,
dans le sens où elle renvoient des lignes. Cela inclut
SHOW
,
DESCRIBE
,
et
EXPLAIN
. Elles doivent être traitées de la même façon que les requêtes
SELECT
.)
Il y'a deux façons pour un client de gérer les jeux de résultats. Une méthode consiste
à récupérer le jeu de résultat en entier et en une seule fois en appelant
mysql_store_result()
. Cette fonction obtient toutes les lignes retournées
par la requête et les stocke dans le client. La seconde méthode consiste à
initialiser une récupération ligne-par-ligne du jeu de résultats en appelant
mysql_use_result()
. Cette fonction initie la récupération, mais ne récupère
actuellement aucune ligne à partir du serveur.
Dans les deux cas, vous accédez aux ligne en appelant
mysql_fetch_row()
.
Avec
mysql_store_result()
,
mysql_fetch_row()
accède aux lignes qui
ont déjà été récupérées à partir du serveur. Avec
mysql_use_result()
,
mysql_fetch_row()
récupère actuellement la ligne à partir du serveur.
Les informations à propos de la taille des données dans chaque ligne est disponible
en appelant
mysql_fetch_lengths()
.
Après avoir fini de traiter le jeu de résultats, appelez
mysql_free_result()
pour libérer la mémoire utilisée.
Les deux mécanismes de récupération sont complémentaires. Les programmes clients doivent
utiliser l'approche qui leur convient le mieux. En pratique, les clients tendent plus
à utiliser
mysql_store_result()
.
Un avantage de
mysql_store_result()
est que puisque toutes les lignes ont
été récupérées dans le client, vous ne pouvez pas que accéder aux lignes séquentiellement,
vous pouvez revenir en arrière ou avancer dans le jeu de résultats en utilisant
mysql_data_seek()
ou
mysql_row_seek()
pour changer la position de la ligne
courante dans le jeu de résultats. Vous pouvez aussi trouver le nombre total des lignes
en appelant
mysql_num_rows()
. D'un autre côté, les besoins en mémoire de
mysql_store_result()
peuvent être très grands pour les grands jeux de résultats
et vous aurez des chances de rencontrer des conditions out-of-memory.
Un avantage de
mysql_use_result()
est que le client a besoinde moins de
mémoire pour le jeu de résultats car il utilise une ligne à la fois (et puisque
il y'a moins de pertes de mémoire,
mysql_use_result()
peut être plus rapide).
Les inconvénients sont que vous devez récupérer chaque ligne rapidement pour éviter
de bloquer le serveur, vous n'avez pas d'accès aléatoires aux lignes dans le jeu de
résultats (vous ne pouvez accéder aux lignes que séquentiellement), et vous ne savez
pas combien de lignes comporte le jeu de résultats tant que vous ne les avez pas
toutes récupérées. De plus, vous
devez
récupérer toutes les lignes même
si vous trouvez entre-temps l'informations que vous cherchiez.
L'API permet aux clients de gérer correctement les requêtes (récupérant les lignes seulement en cas
de besoin) sans savoir si la requête était un
SELECT
ou non. Vous pouvez faire cela en appelant
mysql_store_result()
après chaque
mysql_query()
(ou
mysql_real_query()
).
Si l'appel au jeu de résultats réussi, la requête
était un
SELECT
et vous pouvez lire les lignes. Sinon, appelez
mysql_field_count()
pour vérifier si un résultat aurait du être
retourné. Si
mysql_field_count()
retourne zéro, la requête n'a
pas retourné de données (cela indique que c'était un
INSERT
,
UPDATE
,
DELETE
, etc.), et ne devait pas retourner de lignes.
Si
mysql_field_count()
est non-nul, la requête aurait du retourner
des lignes, mais ne l'a pas fait. Cela indique que la requête était un
SELECT
qui a échoué. Reportez vous à la description de
mysql_field_count()
pour un exemple d'utilisation.
mysql_store_result()
et
mysql_use_result()
vous permettent d'obtenir
des informations à propos des champs qui constituent le jeu de résultat (le nombre de
champs, leurs noms et types, etc.). Vous pouvez accéder aux informations du champ
séquentiellement dans une ligne en appelant plusieurs fois
mysql_fetch_field()
,
ou avec le numéro du champ dans la ligne en appelant
mysql_fetch_field_direct()
.
La position courante du pointeur de champ peut être changée en appelant
mysql_field_seek()
. Changer le pointeur de champ affecte les appels suivants
à
mysql_fetch_field()
. Vous pouvez aussi obtenir en une seule fois
les informations sur les champs en appelant
mysql_fetch_fields()
.
Pour détecter les erreurs, MySQL fournit un accès aux informations des erreurs
via les fonctions
mysql_errno()
et
mysql_error()
.
Elles retournent le code de l'erreur et le message pour la dernière fonction invoquée
qui aurait pu réussir ou échouer, vous permettant ainsi de déterminer les erreurs
et leurs causes.
|
