27.7.5 C API 函数概述

下 table 总结了 C API 中可用的功能。有关更多详细信息，请参见第 27.7.6 节“ 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()：提交 Transaction。

• 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()：返回下一个 table 格字段的类型。

• mysql_fetch_field_direct()：给定字段编号，返回 table 字段的类型。

• 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()：以字符串形式返回 Client 端版本信息。

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

• 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()：返回与简单正则 table 达式匹配的数据库名称。

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

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

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

• 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()：刷新或重置 table 和缓存。

• mysql_reload()：告诉服务器重新加载授权 table。

• 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()：将本地加载数据处理程序回调设置为其默认值。

• mysql_set_local_infile_handler()：安装特定于应用程序的本地加载数据处理程序回调。

• mysql_set_server_option()：设置连接选项(例如multi-statements)。

• mysql_sqlstate()：返回上一个错误的 SQLSTATE 错误代码。

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

• mysql_ssl_set()：准备与服务器构建 SSL 连接。

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

• mysql_store_result()：向 Client 端检索完整的结果集。

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

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

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

• mysql_thread_safe()：如果 Client 端被编译为线程安全的，则返回 1.

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

• mysql_warning_count()：返回上一条 SQL 语句的警告计数。

应用程序应使用以下概述与 MySQL 进行交互：

• 通过调用mysql_library_init()初始化 MySQLClient 端库。该函数同时存在于libmysqlclient CClient 端库和libmysqld嵌入式服务器库中，因此无论是通过与-libmysqlclient标志链接来构建常规 Client 端程序，还是通过与-libmysqld标志链接来构建嵌入式服务器应用程序，都可以使用该函数。

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

• 发出 SQL 语句并处理其结果。 (以下讨论提供了有关如何执行此操作的更多信息.)

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

• 通过调用mysql_library_end()结束对 MySQLClient 端库的使用。

调用mysql_library_init()和mysql_library_end()的目的是提供 MySQLClient 端库的正确初始化和完成。对于与 Client 端库链接的应用程序，它们提供了改进的内存 Management。如果不调用mysql_library_end()，则会保留一块内存。 (这不会增加应用程序使用的内存量，但是某些内存泄漏检测器会抱怨它.)对于与嵌入式服务器链接的应用程序，这些调用会启动和停止服务器。

在非多线程环境中，可以省略对mysql_library_init()的调用，因为mysql_init()将根据需要自动调用它。但是，mysql_library_init()在多线程环境中不是线程安全的，因此mysql_init()也不是，它调用mysql_library_init()。无论是调用mysql_library_init()还是间接通过mysql_init()，都必须在生成任何线程之前调用mysql_library_init()，或者使用 Mutex 来保护该调用。这应该在任何其他 Client 端库调用之前完成。

要连接到服务器，请调用mysql_init()初始化连接处理程序，然后使用该处理程序调用mysql_real_connect()(以及其他信息，例如主机名，用户名和密码)。连接完成后，请调用mysql_close()终止连接。关闭处理程序后，请勿使用它。

连接后，mysql_real_connect()将reconnect标志(MYSQL结构的一部分)设置为0的值。您可以对mysql_options()使用MYSQL_OPT_RECONNECT选项来控制重新连接行为。如果将标志设置为1，则会导致 Client 端在由于丢失连接而无法执行语句之前尝试重新连接到服务器。

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

对于每个非SELECT查询(例如INSERT，UPDATE，DELETE)，您可以通过调用mysql_affected_rows()来查找更改(受影响)的行数。

对于SELECT查询，您将检索选定的行作为结果集。 (请注意，某些语句类似于SELECT，它们返回行。其中包括SHOW，DESCRIBE和EXPLAIN。与SELECT语句一样对待这些语句。)

Client 有两种方式处理结果集。一种方法是通过调用mysql_store_result()一次检索全部结果集。此函数从服务器获取查询返回的所有行，并将其存储在 Client 端中。第二种方法是让 Client 端通过调用mysql_use_result()来开始逐行结果集检索。此函数将初始化初始化，但实际上不会从服务器获取任何行。

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

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

两种检索机制是互补的。选择最适合每个 Client 端应用程序的方法。实际上，Client 倾向于更常见地使用mysql_store_result()。

mysql_store_result()的优点是，因为所有行都已提取到 Client 端，所以您不仅可以 Sequences 访问行，还可以使用mysql_data_seek()或mysql_row_seek()在结果集中来回移动以更改结果集中的当前行位置。您还可以通过调用mysql_num_rows()找出多少行。另一方面，对于较大的结果集，mysql_store_result()的内存要求可能很高，并且您更有可能遇到内存不足的情况。

mysql_use_result()的一个优点是 Client 端需要较少的内存来存储结果集，因为它一次只能维护一行(并且由于分配开销较小，因此mysql_use_result()可以更快)。缺点是您必须快速处理每一行以避免阻塞服务器，您不能随机访问结果集中的行(只能 Sequences 访问行)，并且直到您知道结果集中的行数为止都找回了。此外，即使您在检索中确定您已找到所需的信息，也必须*检索所有行。

该 API 使 Client 端可以在不知道该语句是否为SELECT的情况下适当地响应该语句(仅在必要时检索行)。您可以通过在每个mysql_query()(或mysql_real_query())之后调用mysql_store_result()来实现。如果结果集调用成功，则该语句为SELECT，您可以读取行。如果结果集调用失败，则调用mysql_field_count()来确定结果是否实际上是预期的。如果mysql_field_count()返回零，则该语句不返回任何数据(table 明它是INSERT，UPDATE，DELETE等)，并且不希望返回任何行。如果mysql_field_count()不为零，则该语句应返回行，但不是。这 table 明该语句是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()函数提供对错误信息的访问。它们为成功或失败的最近调用的函数返回错误代码或错误消息，使您能够确定何时发生错误以及发生了什么错误。