C语言的MySQL接口详解

介绍一个MySQL 的关于C语言的接口

mysql_character_set_name()

• const char* mysql_character_set_name(MYSQL* mysql)
• 为当前连接返回默认的字符集
• 返回值：默认的字符集

mysql_close()

• void mysql_close(MYSQL* mysql)
• 描述：关闭前面打开的连接，如果句柄是由 mysql_init() 或者 mysql_connect() 自动分配的，mysql_close() 还将解除分配由 mysql 指向的连接句柄。

mysql_data_seek()

• void mysql_data_seek(MYSQL_RES* result, my_ulonglong offset)
• 在查询结果集中寻找任意行。偏移值为行号，范围从0 到mysql_num_rows(result) -1 。
• 该函数要求结果集结构包含查询的所有结果，结果，mysql_data_seek() 仅应与 mysql_store_result() 联合使用，而不是与mysql_use_result()。

mysql_errno()

• unsigned int mysql_errno(MYSQL* mysql)
• 对于由mysql 指定的连接，mysql_errno() 返回最近调用的API 函数的错误代码，该函数调用可能成功也可能失败。
• “0” 返回值表示未出现错误。
• 如果失败，返回上次mysql_xxx() 调用的错误代码。

mysql_error()

• const char* mysql_error(MYSQL* mysql)
• 对于由mysql 指定的连接，对于失败的最近调用的API 函数，mysql_error() 返回包含错误消息的、由NULL 终结的字符串。
• 如果该函数未失败，mysql_error() 的返回值可能是以前的错误，或指明无错误的空字符串。

mysql_fetch_field()

• MYSQL_FIELD* mysql_fetch_field(MYSQL_RES* result)
• 返回采用MYSQL_FIELD 结构的结果集的列。重复调用该函数，以检索关于结果集中所有列的信息。未剩余字段时，mysql_fetch_field() 返回NULL。
• 每次执行新的 SELECT 查询时，将复位mysql_fetch_field() ,以返回关于第一个字段的信息。
• 调用mysql_field_seek()也会影响 mysql_fetch_field() 返回的字段。
• 当前列的 MYSQL_FIELD 结构。如果未剩余任何列，返回NULL。
• 注意：如果调用了mysql_query() 以在表上执行 SELECT，但未调用 mysql_store_result()，如果调用mysql_fetch_field() 以请求BLOB字段的长度，MYSQL 将返回默认的Blob 长度（8KB）。

MYSQL_FIELD* field;
while(field = mysql_fetch_field(result))
	printf("field name %s\n",field->name); //打印出来的是每一列的字段名字

mysql_fetch_fields()

• MYSQL_FIELD* mysql_fetch_fields(MYSQL_RES* result)
• 对于结果集，返回所有MYSQL_FIELD 结构的数组。每个结构提供了结果集中 1 列的字段定义
• 返回值：关于结果集所有列的 MYSQL_FIELD 结构的数组。

	unsigned int num_fields;
	unsigned int i;
	MYSQL_FIELD* fields;

	num_fields = mysql_num_fields(res);
	fields = mysql_fetch_field(res);
	for (i = 0; i < num_fields; ++i)
		printf("Field %u is %s\n", i, fields[i].name);

mysql_fetch_lengths()

• unsigned long* mysql_fetch_lengths(MYSQL_RES* result )
• 返回结果集当前行的列的长度。
• 如果结果集包含二进制数据，必须使用该函数来确定数据的大小，原因在于，对于包含NULL 字符的任何字段，strlen() 将返回错误的结果。
• 返回值：无符号长整数的数组表示各列的大小（不包含任何终结NULL字符）。如果出现错误，返回NULL

	MYSQL_ROW row;
	unsigned long *lengths;
	unsigned int num_fields;
	unsigned int i;

	mysql_data_seek(res, 1);

	row = mysql_fetch_row(res);
	if (row)
	{
		num_fields = mysql_num_fields(res);
		lengths = mysql_fetch_lengths(res);

		for (i = 0; i < num_fields; ++i)
			printf("Column %u is %lu bytes in length.\n", i, lengths[i]);
	}

mysql_fetch_row()

• MYSQL_ROW mysql_fetch_row(MYSQL_RES* result)
• 检索结果集的下一行。在mysql_store_result() 之后使用时，如果没有要检索的行，mysql_fetch_row() 返回NULL
• 行内值的数目由 mysql_num_fields(result) 给出。如果行中保存了调用 mysql_fetch_row() 返回的值，将按照 row[0] 到 row[mysql_num_fields(result)-1 ]，访问这些值的指针。行中的NULL 值由NULL指针指明。
• 可以通过调用 mysql_fetch_lengths() 来获取行中字段值的长度。对于空字段以及包含 NULL 的字段，长度为0.通过检查字段值的指针，能够区分它们。如果指针为NULL，字段为NULL，否则字段为空。
• 返回值：下一行的MYSQL_ROW 结构，如果没有更多要检索的行或出现了错误，返回NULL。

MYSQL_ROW row;
unsigned int num_fields;
unsigned int i;

num_fields = mysql_num_fields(result);
while(row = mysql_fetch_row(result))
{
	unsigned long * lengths;
	lengths = mysql_fetch_lengths(result);
	for(i = 0;i < num_fields; ++i)
		printf("[%.*s] ",(int)lengths[i], row[i] ? row[i] : "NULL");
	printf("\n");
}

mysql_field_count()

• unsigned int mysql_field_count(MYSQL* mysql)
• 返回作用在连接上的最近查询的列数
• 该函数的正常使用是在 mysql_store_result() 返回 NULL（因而没有结果集指针）时。在这种情况下，可调用 mysql_field_count() 来判定 mysql_store_result() 是否应生成非空结果。这样客户端就能采取恰当的动作，而无需知道查询是否是 SELECT （或类似的SELECT的）语句。

mysql_field_seek()

• MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES* result, MYSQL_FIELD_OFFSET offset)
• 将字段光标设置到给定的偏移处。对 mysql_fetch_field() 下一次调用将检索与该偏移相关的列定义。
• 要想查找行的开始，请传递值为 0 的偏移量。
• 返回值：字段光标的前一个值。

mysql_field_tell()

• MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES* result)
• 返回光标的当前偏移量

mysql_free_result()

• 释放为结果集分配的内存。完成对结果集的操作后，必须调用mysql_free_result() 释放结果集使用的内存。
• 释放完成后，不要尝试访问结果集

mysql_get_character_set_info()

• void mysql_get_character_set_info(MYSQL* mysql, MY_CHARSET_INFO* cs)
• 该函数提供了关于默认客户端字符集的信息。可以使用mysql_set_character_set() 函数更改默认的字符集。

mysql_init()

• MYSQL* mysql_init(MYSQL* mysql)
• 分配或者初始化与mysql_real_connect() 相适应的MYSQL对象。如果mysql 是NULL指针，该函数将分配、初始化、并返回新对象。否则，将初始化对象，并返回对象的地址。
• 如果mysql_init() 分配了新的对象，当调用mysql_close() 来关闭连接时。将释放该对象。
• 返回值：初始化的MYSQL* 句柄。如果无足够内存以分配新的对象，返回NULL。

mysql_list_dbs()

• MYSQL_RES* mysql_list_dbs(MYSQLmysql,const char wild)
• 返回由服务器上的数据库名称组成的结果集，该服务器与由通配符参数指定的简单正则表达式匹配。通配符参数可以包含"%"或“_“，也可以是NULL，以便于所有的数据库匹配。
• 调用mysql_list_dbs() 的方法类似于执行查询 SHOW databases
• 必须用mysql_free_result() 释放结果集
• 返回值：成功后返回 MYSQL_RES 结果集。如果出现错误，返回NULL。

mysql_list_fields()

• MYSQL_RES* mysql_list_fields(MYSQL* mysql,const char* table,const char* wild)
• 返回由给定表中的字段名称组成的结果集，给定表与由通配符参数指定的简单正则表达式匹配。通配符参数可以包含通配符”%“或”_“,也可以是NULL 指针，以便与所有的字段匹配。
• 调用 mysql_list_fields() 方法类似于执行查询 SHOW COLUMNS FROM tal_name。
• 返回值：如果成功，返回 MYSQL_RES 结果集。如果出现错误，返回NULL。

mysql_list_tables()

• MYSQL_RES* mysql_list_tables(MYSQLmysql,const char wild)
• 返回值：返回由当前数据库内的表名组成的结果集，当前的数据库与由通配符参数指定的简单正则表达式匹配。通配符参数可以包含通配符”%“或”_“，也可以是NULL指针，以便与其他所有的表匹配。
• 调用mysql_list_tables() 的方法类似于执行查询 SHOW tables;
• 返回值：如果成功，返回MYSQL_RES结果集。如果出现错误，返回NULL。

mysql_num_rows()

• my_ulonglong mysql_num_rows(MYSQL_RES* result)
• 返回结果集中的行数
• 如果使用了mysql_store_result()，可以立即调用mysql_num_rows()。
• 如果使用了mysql_use_result(),mysql_num_rows() 不返回正确的值，直至检索出结果集中所有行为为止。
• 返回值：结果集中的行数。

mysql_options()

• int mysql_options(MYSQL* mysql,enum mysql_option option,const char* arg)
• 可用于设置额外的连接选项，并影响连接的行为。可多次调用该函数来设置数个选项。
• 应在mysql_init() 之后、以及 mysql_connect() 或 mysql_real_connect() 之前调用 mysql_options()
• 选项参量指的是你打算设置的选项，Arg 参数是选项的值。如果选项是整数，那么arg 应指向整数的值。
• 可能的选项值我不在此列出了，大家自行百度。
• 返回值：成功时返回0，如果使用了未知选项，那么返回非0值。

mysql_ping()

• int mysql_ping(MYSQL*mysql)
• 检查与服务器的连接是否工作。如果工作丢失，将自动尝试再连接。
• 该函数可被闲置了较长时间的客户端使用，用以检查服务器是否已关闭了连接，并在必要的时候再次连接。
• 返回值：如果与服务器的连接有效返回0，如果出现错误，返回非0值。返回的非0值不表示MYSQL 服务器本省是否已关闭，连接可能因其他原因终端，如网络问题呢。

mysql_query()

• int mysql_query(MYSQL* mysql,const char* query)
• 执行由“NULL 终结的字符串”查询指向的SQL查询。正常情况下，字符串必须包含一条SQL语句，而且不应该为语句添加分号“;”或者“\g”。
• mysql_query() 不能用于包含二进制数据的查询，应使用mysql_real_query() 取而代之，因为二进制数据可能包含字符“\0”，mysql_query() 会将该字符解释为查询字符串结束。
• 如果查询成功，返回0，如果出现错误，返回非0值。

mysql_real_connect()

• MYSQL* mysql_real_connect(MYSQL* mysql,const char* host,const char* user,const char* passwd,const char* db,const char* unix_socket,unsigned long client_flag)
• mysql_real_connect() 尝试与运行在主机上的MYSQL 数据库引擎建立连接。在你能够执行需要有效的 MYSQL 连接句柄机构的任何其他API 函数之前，mysql_real_connect() 必须成功完成。
• 第一个参数应是已有的MYSQL 结构的地址。调用mysql_init() 来初始化MYSQL 结构。
• 第二个参数 host 的值必须是主机名或者IP地址。如果host 是NULL或者字符串“localhost”，连接将被视为与本地主机的连接。如果操作系统支持套接字Unix 或这命名管道 Windows ，将使用它们而不是 TCP/IP 连接到服务器。
• 第三个参数user 参数包含用户的MYSQL 登录 ID。如果user 是NULL 或空字符串，用户将被视为当前用户。在UNIX 环境下，他是当前的登录名。在windows下，必须指明当前用户名。
• passwd 参数包含用户的密码。如果passwd 是NULL，仅会对该用户的（拥有一个空密码字段）用户表中的条目进行匹配检查。这样，数据库管理员就能按特定的方式设置MYSQL 权限系统，根据用户是否拥有指定的密码，用户将获得不同的权限。
• 注意：调用mysql_real_connect() 之前，不要尝试加密密码，密码加密将由客户端API 自动处理。
• “db”是数据库名称，如果db 是NULL，连接会将默认的数据库设为此值。
• 如果port 不是0，其值将用做 TCP/IP 连接的端口号。注意，host 参数决定了连接的类型。
• 如果 unix_socket 不是NULL，该字符串描述了应使用套接字或命名管道。注意：“host” 参数决定了连接的类型。
• client_flag 的值通常是0，但是，也可以设立标志位。我不介绍，自行谷歌。
• 返回值：如果连接成功，返回MYSQL* 连接句柄。如果连接失败，返回NULL。对于连接成功的连接，返回值与第一个参数的值相同。

mysql_real_query()

• int mysql_real_query(MYSQL* mysql,const char* query,unsigned long length)
• 执行由“query” 指向的SQL查询，它应是字符串长度字节“long”。正常情况下，字符串必须包含一个SQL语句，而且不应该为语句添加“；”或者“\g”。
• 对于包含二进制数据的查询，必须使用mysql_real_query() 而不是 mysql_query() ，这是因为，二进制数据可能会包含“\0”字符。此外，mysql_real_query() 比 mysql_query() 快，这是因为他不会在查询字符串上调用strlen()。
• 如果查询成功，返回0。如果出现错误，返回非0值。

mysql_row_seek()

• MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES* result, MYSQL_ROW_OFFSET offset)
• 将行坐标置于查询结果集中的任意行。offset 是行偏移量，它应是从mysql_row_tell() 或 mysql_row_seek() 返回的值。该值不是行编号，如果你打算按编号查询结果集中的行，请使用 mysql_data_seek()
• 该函数要求在结果集中查询的全部结果，因此，mysql_row_seek() 仅应于 mysql_store_result() 一起使用，而不是与 mysql_use_result()。
• 行坐标的前一个值，该值可传递给对mysql_row_seek() 的后续使用。

mysql_row_tell()

• MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES* result)
• 对于上一个 mysql_fetch_row()，返回光标的当前位置。该值可用作mysql_row_seek() 的参量。
• 仅可以用在mysql_store_result() 之后，而不是mysql_use_result() 之后。
• 返回值：行坐标的当前偏移量

mysql_set_character_set()

• int mysql_set_character_set(MYSQL* mysql, char* csname)
• 该函数用于当前连接设置默认的字符集。字符串csname指定 一个有效的字符集名称。连接校对成为字符集的默认校对。
• 返回值：0表示成功，非0值表示出现错误

if(!mysql_set_charset_name(&mysql,"utf8"))
{
	printf("New client character set : %s\n", mysql_character_set_name(&mysql));
}

mysql_shutdown()

• int mysql_shutdown(MYSQL* mysql, enum enum_shutdown_level shutdown_level)
• 请求数据库服务器关闭。要保证已连接的用户必须具有SHUTDOWN 权限。
• 返回值：0 表示成功，非0值表示出现了错误。

mysql_store_result()

• MYSQL_RES* mysql_store_result(MYSQL*mysql)
• 对于成功检索了数据的每个查询（SELECT、SHOW、DESCRIBE、EXPLAIN、CHECK TABLE等），必须调用mysql_store_result() 或mysql_use_store()。
• mysql_store_result() 将查询的全部结果读取到客户端，分配一个MYSQL_RES 结构，并将结果置于该结构中。
• 如果查询未返回结果集，mysql_store_result() 将返回NULL 指针
• 如果读取结果集失败，mysql_store_result() 还会返回NULL 指针，通过检查mysql_error()是否返回非空字符串，mysql_errno() 是否返回非0值，可以检查是否出现了错误。
• 如果未返回行，将返回空的结果集。（空结果集设置不同于作为返回值的空指针）
• 一旦调用了mysql_store_result() 并获得了不是NULL 指针的结果，可调用mysql_num_rows() 来找出结果集中的行数。
• 可以调用mysql_fetch_row() 来获取结果集中的行，或调用mysql_row_seek() 或mysql_row_tell() 来获取或设置结果集中的当前行位置。
• 一旦完成了对结果集的操作，必须调用mysql_free_result()。
• 返回值：具有多个结果的MYSQL_RES结果集合。如果出现错误，返回NULL。

mysql_use_result()

• MYSQL_RES* mysql_use_result(MYSQL* mysql)
• mysql_use_result 将初始化结果集检索，但并不像mysql_store_result() 那样将结果集实际读取到客户端。它必须通过对mysql_fetch_row() 的调用，对每一行分别进行检索。这将直接从服务器读取结果，而不会将其保存到临时表或本地缓冲区内，与mysql_store_result() 相比，速度更快而且使用的内存更少。客户端仅为当前行和通信缓存区进行分配内存。
• 如果使用了mysql_use_result() ，这会绑定服务器，并阻止其他线程更新任何表。
• 使用mysql_use_result()时，必须执行mysql_fetch_row()，直至返回NULL值，否则，未获取的行将作为下一个检索的一部分返回。
• 不应与从mysql_use_result() 返回的结果一起使用mysql_data_seek() 、 mysql_row_seek()、mysql_row_tell()、mysql_num_row()，也不应该发起其他查询，直至mysql_use_result() 完成为止。
• 一旦完成了对结果集的操作，必须调用mysql_free_result()。

还有一些接口，我暂时开发中没有用到，后面如果有用到，我会更新。