MySQL C API概述

时间:2023-03-08 17:40:22

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

应用程序应该使用这个总体大纲来与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()返回零,声明没有返回数据(表明它是一个 INSERTUPDATE, 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()函数提供对错误信息的访问 。这些将返回最近调用的函数的错误代码或错误消息,这些函数可以成功或失败,从而使您能够确定错误何时发生以及发生了什么。