MySQL C API概述

以下列表总结了C API中可用的功能。有关更多详细信息，请参见 第27.8.7节“C API函数描述”中的说明。

• my_init()：在线程安全程序中初始化全局变量和线程处理程序

• mysql_affected_rows()：返回改变的行数/删除/插入的最后 UPDATE， DELETE或 INSERT查询

• mysql_autocommit()：打开/关闭自动提交模式

• mysql_change_user()：在打开的连接上更改用户和数据库

• mysql_character_set_name()：返回当前连接的默认字符集名称

• mysql_client_find_plugin()：返回指向插件的指针

• mysql_client_register_plugin()：注册一个插件

• mysql_close()：关闭服务器连接

• mysql_commit()：提交交易

• mysql_connect()：连接到MySQL服务器（此功能已弃用;请 mysql_real_connect()改用）

• mysql_create_db()：创建一个数据库（此功能已弃用;请改用SQL语句 CREATE DATABASE）

• mysql_data_seek()：查询查询结果集中的任意行号

• mysql_debug()： DBUG_PUSH与给定的字符串

• mysql_drop_db()：删除数据库（此功能已弃用;请改用SQL语句 DROP DATABASE）

• mysql_dump_debug_info()：使服务器将调试信息写入日志

• mysql_eof()：确定结果集的最后一行是否已被读取（此功能已被弃用; mysql_errno()或者 mysql_error()可用于替代）

• mysql_errno()：返回最近调用的MySQL函数的错误号

• mysql_error()：返回最近调用的MySQL函数的错误消息

• mysql_escape_string()：转义字符串中的特殊字符以用于SQL语句

• mysql_fetch_field()：返回下一个表格字段的类型

• mysql_fetch_field_direct()：给定一个字段号，返回一个表字段的类型

• mysql_fetch_fields()：返回所有字段结构的数组

• mysql_fetch_lengths()：返回当前行中所有列的长度

• mysql_fetch_row()：从结果集中获取下一行

• mysql_field_count()：返回最近语句的结果列数

• mysql_field_seek()：将列光标放在指定的列上

• mysql_field_tell()：返回用于最后一个的字段光标的位置 mysql_fetch_field()

• mysql_free_result()：释放结果集使用的内存

• mysql_get_character_set_info()：返回有关默认字符集的信息

• mysql_get_client_info()：将客户端版本信息作为字符串返回

• mysql_get_client_version()：以整数形式返回客户端版本信息

• mysql_get_host_info()：返回描述连接的字符串

• mysql_get_option()：返回mysql_options() 选项 的值

• mysql_get_proto_info()：返回连接使用的协议版本

• mysql_get_server_info()：返回服务器版本号

• mysql_get_server_version()：以整数形式返回服务器的版本号

• mysql_get_ssl_cipher()：返回当前的SSL密码

• mysql_hex_string()：以十六进制格式编码字符串

• mysql_info()：返回有关最近执行的查询的信息

• mysql_init()获取或初始化MYSQL结构

• mysql_insert_id()：返回AUTO_INCREMENT上一个查询为列 生成的ID

• mysql_kill()：杀死给定的线程

• mysql_library_end()：完成MySQL C API库

• mysql_library_init()：初始化MySQL C API库

• mysql_list_dbs()：返回与简单正则表达式匹配的数据库名称

• mysql_list_fields()：返回匹配简单正则表达式的字段名称

• mysql_list_processes()：返回当前服务器线程的列表

• mysql_list_tables()：返回匹配简单正则表达式的表名

• mysql_load_plugin()：加载一个插件

• mysql_load_plugin_v()：加载一个插件

• mysql_more_results()：检查是否存在更多结果

• mysql_next_result()：返回/启动多重结果执行中的下一个结果

• mysql_num_fields()：返回结果集中的列数

• mysql_num_rows()：返回结果集中的行数

• mysql_options()：为连接选项设置 mysql_real_connect()

• mysql_options4()：为连接选项设置 mysql_real_connect()

• mysql_ping()：检查到服务器的连接是否正常工作，必要时重新连接

• mysql_plugin_options()：设置一个插件选项

• mysql_query()：执行指定为空终止字符串的SQL查询

• mysql_real_connect()：连接到MySQL服务器

• mysql_real_escape_string()：考虑到连接的当前字符集，转义字符串中的特殊字符以用于SQL语句

• mysql_real_escape_string_quote()：转义字符串中的特殊字符以便在SQL语句中使用，同时考虑连接的当前字符集和引用上下文

• mysql_real_query()：执行指定为计数字符串的SQL查询

• mysql_refresh()：刷新或重置表格和缓存

• mysql_reload()：通知服务器重新加载授权表

• mysql_reset_connection()：重置连接以清除会话状态

• mysql_rollback()：回退交易

• mysql_row_seek()：使用返回的值寻找结果集中的行偏移量 mysql_row_tell()

• mysql_row_tell()：返回行光标位置

• mysql_select_db()：选择一个数据库

• mysql_server_end()：完成MySQL C API库

• mysql_server_init()：初始化MySQL C API库

• mysql_session_track_get_first()：获取会话状态更改信息的第一部分

• mysql_session_track_get_next()：获取会话状态更改信息的下一部分

• mysql_set_character_set()：为当前连接设置默认字符集

• mysql_set_local_infile_default()：将LOAD DATA LOCAL INFILE处理程序回调设置为其默认值

• mysql_set_local_infile_handler()：安装特定于应用程序的 LOAD DATA LOCAL INFILE处理程序回调

• mysql_set_server_option()：为连接设置一个选项（如 multi-statements）

• mysql_sqlstate()：返回最后一个错误的SQLSTATE错误代码

• mysql_shutdown()：关闭数据库服务器

• mysql_ssl_set()：准备建立到服务器的SSL连接

• mysql_stat()：以字符串形式返回服务器状态

• mysql_store_result()：检索完整的结果集给客户端

• mysql_thread_end()：完成线程处理程序

• mysql_thread_id()：返回当前的线程ID

• mysql_thread_init()：初始化线程处理程序

• mysql_thread_safe()：如果客户端编译为线程安全，则返回1

• mysql_use_result()：启动逐行结果集检索

• mysql_warning_count()：返回以前的SQL语句的警告计数

应用程序应该使用这个总体大纲来与MySQL进行交互：

1. 通过调用初始化MySQL客户端库 mysql_library_init()。该功能既存在于libmysqlclient C客户端库中，也存在于libmysqld嵌入式服务器库中，因此无论您是通过与-libmysqlclient标志链接来构建常规客户端程序，还是通过与标志链接来构建 嵌入式服务器应用程序，都可以使用该功能-libmysqld 。

2. 通过调用初始化连接处理程序并通过调用 mysql_init()连接到服务器 mysql_real_connect()。

3. 发出SQL语句并处理它们的结果。（以下讨论提供了有关如何执行此操作的更多信息。）

4. 通过调用关闭与MySQL服务器的连接 mysql_close()。

5. 通过调用最终使用MySQL客户端库 mysql_library_end()。

打电话的目的 mysql_library_init()，并 mysql_library_end()为提供MySQL客户端库提供恰当的初始化和结束。对于与客户端库链接的应用程序，它们提供改进的内存管理。如果你没有调用mysql_library_end()，则会 分配一块内存。（这不会增加应用程序使用的内存量，但有些内存泄​​漏检测器会对此抱怨。）对于与嵌入式服务器链接的应用程序，这些调用会启动和停止服务器。

在非多线程环境中，调用 mysql_library_init()可能会被忽略，因为mysql_init()它会根据需要自动调用它。但是， mysql_library_init()在多线程环境中不是线程安全的，因此也不是 mysql_init()，哪个调用 mysql_library_init()。您必须mysql_library_init() 在产生任何线程之前进行调用，或者使用互斥锁来保护调用，无论是mysql_library_init()通过调用还是间接调用 mysql_init()。这应该在任何其他客户端库调用之前完成。

要连接到服务器，请调用 mysql_init()初始化连接处理程序，然后mysql_real_connect()使用该处理程序（以及其他信息，例如主机名，用户名和密码）进行调用 。连接后， mysql_real_connect()将 reconnect标志（MYSQL结构的一部分 ）设置为 1API 5.0.3以前0版本或 新版本中的值。1此标志的值 表示如果由于连接丢失而无法执行语句，则在放弃之前尝试重新连接到服务器。您可以使用该 MYSQL_OPT_RECONNECT选项 mysql_options()来控制重新连接行为。完成连接后，请致电 mysql_close() 终止它。

当连接处于活动状态时，客户端可以使用mysql_query() 或将SQL语句发送到服务器mysql_real_query()。两者之间的区别在于 mysql_query()期望查询被指定为以空字符结尾的字符串，而 mysql_real_query()期望计数的字符串。如果字符串包含二进制数据（可能包含空字节），则必须使用mysql_real_query()。

对于每个非SELECT查询（例如INSERT， UPDATE， DELETE），你能找出多少行通过调用改变（受影响） mysql_affected_rows()。

对于SELECT查询，您将检索选定的行作为结果集。（请注意，某些语句是 SELECT在样，他们返回行。这些措施包括SHOW， DESCRIBE，和 EXPLAIN。对待这些声明的方式相同SELECT的语句。）

客户端有两种处理结果集的方法。一种方法是通过调用一次检索整个结果集 mysql_store_result()。该函数从服务器获取查询返回的所有行并将它们存储在客户端中。第二种方式是让客户端通过调用来逐行启动结果集检索 mysql_use_result()。该函数初始化检索，但实际上并未从服务器获取任何行。

在这两种情况下，您都可以通过调用访问行 mysql_fetch_row()。使用 mysql_store_result()， mysql_fetch_row()访问先前从服务器获取的行。与 mysql_use_result()， mysql_fetch_row()实际上从服务器检索行。有关每行数据大小的信息可通过调用获得 mysql_fetch_lengths()。

在完成结果集之后，调用 mysql_free_result()释放用于它的内存。

这两种检索机制是互补的。选择最适合每个客户端应用程序的方法。在实践中，客户往往 mysql_store_result()更常用。

其优势 mysql_store_result()在于，因为所有行都被提取到客户端，所以您不仅可以按顺序访问行，还可以使用结果集中的来回移动mysql_data_seek() 或mysql_row_seek()更改结果集中当前行的位置。你也可以通过调用找出有多少行 mysql_num_rows()。另一方面，mysql_store_result()对于大型结果集，内存需求 可能非常高，并且您更可能遇到内存不足的情况。

其优点mysql_use_result() 是客户端对结果集的内存要求较少，因为它一次只维护一行（因为分配开销较少， mysql_use_result()速度可能更快）。缺点是您必须快速处理每一行以避免捆绑服务器，您不能随机访问结果集中的行（您只能按顺序访问行），并且结果集中的行数是未知的，直到您已全部检索到它们。此外， 即使您在检索过程中确定找到了您要查找的信息，也必须检索所有行。

API使得客户端可以对语句作出适当的响应（仅在必要时检索行），而无需知道语句是否为SELECT。你可以mysql_store_result()在每个mysql_query()（或 mysql_real_query()）之后通过调用来 完成 。如果结果集调用成功，则语句为a SELECT，您可以读取行。如果结果集调用失败，请调用 mysql_field_count()以确定结果是否实际上是预期的。如果 mysql_field_count()返回零，声明没有返回数据（表明它是一个 INSERT，UPDATE， DELETE，等等），并没有返回行。如果 mysql_field_count()该语句应该返回行，但不是。这表明该声明是 SELECT失败的。有关mysql_field_count()如何完成这一操作的示例，请参阅说明 。

双方mysql_store_result()并 mysql_use_result()让你获得有关组成结果集（领域，他们的名字和类型的数量，等等）的字段的信息。您可以通过mysql_fetch_field() 重复调用，或通过调用行内的字段编号，在行内 依次访问字段信息mysql_fetch_field_direct()。通过调用可以改变当前的字段光标位置 mysql_field_seek()。设置字段光标会影响后续的呼叫 mysql_fetch_field()。您也可以通过呼叫一次获得所有字段的信息mysql_fetch_fields()。

为了检测和报告错误，MySQL通过mysql_errno()和 mysql_error()函数提供对错误信息的访问 。这些将返回最近调用的函数的错误代码或错误消息，这些函数可以成功或失败，从而使您能够确定错误何时发生以及发生了什么。