MYSQL 语言C API的常用函数

1.MYSQL C API的常用函数

1.1数据类型

MYSQL
该结构代表1个数据库连接的句柄。几乎所有的MYSQL函数均使用它。
MYSQL_RES
该结构代表返回行的查询结果
MYSQL_ROW
这是1行数据的”类型安全”表示。
MYSQL_FIELD
该结构包含关于字段的信息，如字段名、类型和大小等
MYSQL_FIELD_OFFSET
这时MYSQL字段列表偏移量的”类型安全”表示
my_ulonglong
用于行数以及mysql_affected_rows()、mysql_num_rows()和mysql_insert_id()的类型

1.2编程步骤

1 通过调用mysql_library_init(),初始化MYSQL库
2 通过调用mysql_init()初始化连接处理程序，并通过调用mysql_real_connect()连接到服务器
3 发出SQL语句并处理其结果
4 通过调用mysql_close()，关闭与MYSQL服务器的连接
5 通过调用mysql_library_end()，结束MYSQL库的使用

1.3数据库连接

1.3.1初始化一个连接句柄结构
#include
MYSQL mysql_init(MYSQL );
1.3.2和数据库建立物理连接
MYSQL *mysql_real_connect(MYSQL *connection,
const char *server_host,const char *sql_user_name,
const char *sql_password,const char *db_name,
unsigned intport_number,const char
*unix_socket_name,unsignedint flags);
1.3.3连接参数
Intmysql_options(MYSQL *connection,enum
option_to_set,const char *argument)

1.4错误处理

unsigned intmysql_errno(MYSQL *connection);
对于由mysql指定的连接，该函数返回最近调用的API函数的错误代码，该函数调用可能成功也可能失败。”0”返回值表示未出现错误
char *mysql_error(MYSQL *connection)
如果想获得错误的文本信息，可以调用该函数

1.5执行SQL语句

intmysql_query(MYSQL *mysql,const char *query)
功能描述：
执行由”Null终结的字符串”查询指向的SQL查询。正常情况下，字符串必 须 包含1条SQL语句，而且不应为语句添加终结分号或”\g”
不能用于包含二进制数据的查询，应使用mysql_real_query来完成
对于操纵语句

My_ulonglongmysql_affected_rows(MYSQL *mysql)
返回上次操纵语句所涉及到记录的行数
对于UPDATE、DELETE或INSERT语句，可在mysql_query()后立刻调用。对于SELECT语句，该函数的工作方式与mysql_num_rows()类似

对于查询语言
MYSQL_RES *mysql_store_result(MYSQL *mysql)
功能说明：
对于成功检索了数据的每个查询，必须调用mysql_store_result()或mysql_use_result()
该函数将查询的全部结果读取到客户端，分配1个MYSQL_RES结构，并将结果置于该结构中
可以通过mysql_num_rows来找出结果集中的行数

事务处理
my_boolmysql_autocommit(MYSQL *mysql,my_bool mode)
函数说明:如果模式为1,启动autocommit模式；如果模式为0，禁止autocommit模式
my_boolmysql_commit(MYSQL *mysql)
提交当前事务
my_boolmysql_rollback(MYSQL *mysql)
回滚当前事务

处理结果集
MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)
功能描述
检索结果集的下一行
行内值的数目由mysql_num_fields(result)给出

void mysql_data_seek(MYSQL_RES *result,my_ulonglong offset)
功能描述：
在查询结果集中寻找任意行。偏移值为行号。
该函数要求结果集结构包含查询的所有结果

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)
返回光标的当前位置

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result,MYSQL_ROW_OFFSET offset)
将行光标置于查询结果集中的任意行

每次接收一行数据
MYSQL_RES *mysql_use_result(MYSQL *mysql)
功能说明：
不像mysql_store_result()那样把结果集实际读取到客户端。它必须通过对mysql_fetch_row()的调用，对每一行分别进行检索。
Mysql_store_result()相比，速度更快而且使用的内存更少

多查询执行的C API处理
支持在单个字符串中指定的多语句的执行。要想与给定的连接一起使用该功能，打开连接时，必须将标志参数中的CLIENT_MULTI_STATEMENTS选项指定给mysql_real_connect()。也可以通过调用mysql_set_server_option(MYSQL_OPTION_MULTI_STATEMENTS_ON)，为已有的连接设置它

1.5详细api列表

MYSQL *mysql_init(MYSQL *mysql)
分配或初始化与mysql_real_connect()相适应的MYSQL对象。
如果mysql是NULL指针，该函数将分配、初始化、并返回新对象。否则，将初始化对象，并返回对象的地址。
如果mysql_init()分配了新的对象，当调用mysql_close()来关闭连接时。将释放该对象。
void mysql_close(MYSQL *mysql)
关闭前面打开的连接。
如果句柄是由mysql_init()或mysql_connect()自动分配的，mysql_close()还将解除分配由mysql指向的连接句柄。
mysql_real_connect函数
MYSQL *mysql_real_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd, const char *db, unsigned int port, const char *unix_socket, unsigned long client_flag)
函数功能:尝试与运行在主机上的MySQL数据库引擎建立连接
connect = mysql_real_connect(&mysql, “localhost”, “root”, “123456”, “mydb2”, 0, NULL, 0 );

查询api
mysql_query()函数和mysql_real_query()函数
intmysql_query(MYSQL *mysql, const char *query)
intmysql_real_query(MYSQL *mysql, const char *query, unsigned long length)
对于包含二进制数据的查询，必须使用mysql_real_query()而不是mysql_query()，
mysql_real_query()比mysql_query()快，这是因为它不会在查询字符串上调用strlen()。

获取结果集api
mysql_store_result()函数和mysql_use_result
MYSQL_RES *mysql_store_result(MYSQL *mysql)
mysql_store_result()将查询的全部结果读取到客户端，分配1个MYSQL_RES结构，并将结果置于该结构中；
可调用mysql_num_rows()来找出结果集中的行数。可以调用mysql_fetch_row()来获取结果集中的行，或调用mysql_row_seek()和mysql_row_tell()来获取或设置结果集中的当前行位置。
一旦完成了对结果集的操作，必须调用mysql_free_result()。

MYSQL_RES *mysql_use_result(MYSQL *mysql)每次接收一行数据
功能说明：
不像mysql_store_result()那样把结果集实际读取到客户端。它必须通过对mysql_fetch_row()的调用，对每一行分别进行检索。
Mysql_store_result()相比，速度更快而且使用的内存更少

2.1调用思路分析

2.1 简介

访问MySQL服务器，这需要使用mysqlclient库，MySQL的大多数客户端API（除了
Java和.NET）都是通过这个库来和MySQL服务器通讯的，而这个库正是用C编写的。

2.2代码编写和编译

2.3连接MySQL服务器

初始化一个MYSQL结构，该结构在几乎所有的MySQL C API函数（除了预处理语句相关的函数）中都会用到。MYSQL *mysql_init(MYSQL *mysql)
连接MySQL服务器使用MYSQL *mysql_real_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd,const char *db, unsigned int port, const char *unix_socket, unsigned long client_flag);
也可另一种方式来进行连接。先用MYSQL_READ_DEFAULT_FILE作为选项名来调用mysql_options(), 再调用mysql_real_connect()来连接服务器;
mysql_options(*mysql, MYSQL_READ_DEFAULT_FILE, “my.cnf”)
mysql_real_connect(*mysql, NULL, NULL, NULL, NULL, 0, NULL, 0)
说明：my.cnf文件中记录了连接MySQL服务器所需的各项参数（地址，端口，用户名，密
码，数据库，字符集，Unix Socket等）。这样可以灵活的修改连接参数而不必重新编译程序。
要关闭连接，则调用mysql_close()
voidmysql_close(MYSQL *mysql)

2.4执行查询

1）调用mysql_query()来执行SQL语句，如果语句中包含二进制数据，则需要调用
mysql_real_query()
intmysql_query(MYSQL *mysql, const char *stmt_str)
intmysql_real_query(MYSQL *mysql, const char *stmt_str, unsigned long length)

2）若执行的是UPDATE, DELETE或INSERT语句，则可通过mysql_affected_rows()获知
受影响的记录数。my_ulonglongmysql_affected_rows(MYSQL *mysql) 。
还可以通过mysql_insert_id()来获取由最近的UPDATE或INSERT语句生成的自增值。
my_ulonglongmysql_insert_id(MYSQL *mysql)

3）若执行的是SELECT语句，则有两种方式来获取结果集。
3-1）一种方式是通过mysql_store_result()将整个结果集全部取回来。
MYSQL_RES *mysql_store_result(MYSQL *mysql)
3-2）另一种方式则是调用mysql_use_result()初始化获取操作，但暂时不取回任何记录。MYSQL_RES *mysql_use_result(MYSQL *mysql)；
3-3两种方法均通过mysql_fetch_row()来访问每一条记录。
MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)
注意：若先前调用的是mysql_store_result(), 则直接在本地访问记录；若先前调用的是mysql_use_result(), 则此时才到服务器上去获取记录。

4）当处理完结果集后，调用mysql_free_result()来释放它所占的内存。void mysql_free_result(MYSQL_RES *result)。

5）可调用mysql_errno()和mysql_error()来获知最近执行的API函数的错误代码和错误信息。
unsignedintmysql_errno(MYSQL *mysql)
const char *mysql_error(MYSQL *mysql)

2.5. 预处理语句(Prepared Statements)

MySQL C API还提供了另一种方式来执行SQL语句，即先预处理(prepare)再执行
(execute). 对于多次执行的SQL语句，该方式可以提高其执行效率。具体步骤如下：

1. 调用mysql_stmt_init()创建语句句柄，该句柄在随后的函数调用中都要用到。
   MYSQL_STMT *mysql_stmt_init(MYSQL *mysql)

2. 调用mysql_stmt_prepare()对SQL语句进行预处理
   intmysql_stmt_prepare(MYSQL_STMT *stmt, const char *stmt_str, unsigned long length)

3. 如果SQL语句中有参数，则需要调用mysql_stmt_bind_param()进行参数绑定。
   my_boolmysql_stmt_bind_param(MYSQL_STMT *stmt, MYSQL_BIND *bind)
   如果参数的类型为TEXT或BLOB, 并且数据量很大，可以调用
   mysql_stmt_send_long_data()来向服务器发送数据。
   my_boolmysql_stmt_send_long_data(MYSQL_STMT *stmt, unsigned intparameter_number, const char *data, unsigned long length)

4. 调用mysql_stmt_execute()来执行查询。
   intmysql_stmt_execute(MYSQL_STMT *stmt)

5. 若查询不产生结果集，可以调用
   mysql_stmt_affected_rows()和
   my_ulonglongmysql_stmt_insert_id(MYSQL_STMT *stmt)来获得被改变的记录数和生成的自增值。
   my_ulonglongmysql_stmt_affected_rows(MYSQL_STMT *stmt)
   my_ulonglongmysql_stmt_insert_id(MYSQL_STMT *stmt)
   否则，执行mysql_stmt_bind_result()对结果集中的字段进行绑定。
   my_boolmysql_stmt_bind_result(MYSQL_STMT *stmt, MYSQL_BIND *bind)

2.6. 调用mysql_stmt_fetch()来逐行获取结果集中的记录。

intmysql_stmt_fetch(MYSQL_STMT *stmt)
在调用mysql_stmt_fetch()之前，还可以执行mysql_stmt_store_result()将结果
集预先缓存到本地。
intmysql_stmt_store_result(MYSQL_STMT *stmt)

2.7. 重复步骤3-6, 每次使用不同的实参来执行查询。

2.8. 调用mysql_stmt_close()关闭句柄，释放资源

my_boolmysql_stmt_close(MYSQL_STMT *)
此外，可以调用mysql_stmt_errno()和mysql_stmt_error()来获知最近执行的预处
理语句API函数的错误代码和错误信息。
unsignedintmysql_stmt_errno(MYSQL_STMT *stmt)
const char *mysql_stmt_error(MYSQL_STMT *stmt)

2.9.其他说明：

mysql_stmt_execute()中有调用案例
http://dev.mysql.com/doc/refman/5.1/zh/apis.html#c-api-multiple-queries
25.2.7.11. mysql_stmt_fetch()