Types de données de l'API C
<<<		 Vue d'ensemble des fonctions de l'API C Description des fonctions de l'API C
>>>
21.2 API MySQL C
21 API 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
. Fonctions C de commandes préparées
. Types de données de l'API C
. Présentation des fonctions de l'interface C
. Descriptions des fonctions C pour les requêtes préparées
. Gestion des commandes multiples avec l'interface C
. Gestion des dates et horaires avec l'interface C
. Description des fonctions threadées de C
. Description des fonctions C du serveur embarqué
. Questions courantes sur la bibliothèque C
. Compiler les clients
. Comment faire un client MySQL threadé
. libmysqld , la bibliothèque du serveur embarqué MySQL

21.2.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 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 sous forme de chaîne.
mysql_get_client_version() Retourne la version du client sous forme d'entier.
mysql_get_host_info() Retourne une chaîne décrivant la connexion.
mysql_get_server_version() Retourne le numéro de version du serveur sous forme d'entier (nouveau en 4.1).
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écifié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_set_server_option() Spécifie la valeur d'une option pour la connexion (comme multi-statements ).
mysql_sqlstate() Retourne l'erreur SQLSTATE de la dernière erreur.
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ésultats complet dans le client.
mysql_thread_id() Retourne l'identifiant du thread courant.
mysql_thread_safe() Retourne 1 si le client est compilé avec la sécurité thread.
mysql_use_result() Initialise une récupération ligne par ligne des résultats.
mysql_warning_count() Retourne le nombre d'alertes générées par la dernière commande SQL.
mysql_commit() Valide une transaction (nouveau en 4.1).
mysql_rollback() Annule une transaction (nouveau en 4.1).
mysql_autocommit() Active et désactive le mode d'auto validation (nouveau en 4.1).
mysql_more_results() Vérifie si il n'y a plus de résultats (nouveau en 4.1).
mysql_next_result() Retourne/initie le prochain résultat dans une commande multi-requête (nouveau en 4.1).
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 d'obtenir un manque de mémoire.

Un avantage de mysql_use_result() est que le client a besoin de 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.
<< Vue d'ensemble des fonctions de l'API C >>
Types de données de l'API C API MySQL C Description des fonctions de l'API C