libmysqlclient 常用api学习

在开始、提交、回滚事务时推荐使用SQL语句START TRANSACTIONCOMMITROLLBACK然后执行进行操作,可以统一断线重连的处理逻辑。

api使用流程图

libmysqlclient api

mysql_init

原型: MYSQL *mysql_init(MYSQL *mysql)
描述: 分配或初始化与mysql_real_connect()相适应的MYSQL对象.如果mysql是NULL指针,该函数将分配、初始化、并返回新对象.否则,将初始化对象,并返回对象的地址. 如果mysql_init()分配了新的对象,当调用mysql_close()来关闭连接时.将释放该对象.
返回值: 初始化的MYSQL*句柄.如果无足够内存以分配新的对象,返回NULL.
错误: 在内存不足的情况下,返回NULL.

mysql_close

原型: void mysql_close(MYSQL *mysql)
描述: 关闭前面打开的连接.如果句柄是由mysql_init()mysql_connect()自动分配的,mysql_close()还将解除分配由mysql指向的连接句柄.
返回值: 无
错误: 无

mysql_options

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_real_connect()尝试与运行在主机上的MySQL数据库引擎建立连接.在执行需要有效MySQL连接句柄结构的任何其他API函数之前,mysql_real_connect()必须成功完成.
参数的指定方式如下:

* `mysql`应是已有MYSQL结构的地址.调用`mysql_real_connect()`之前,必须调用`mysql_init()`来初始化MYSQL结构.通过`mysql_options()`调用,可更改多种连接选项.
* `host`的值必须是主机名或IP地址
* `user`用户的MySQL登录名
* `passwd`用户的密码
* `db`数据库名称
* `port`端口号
* `unix_socket`表示连接类型
* `client_flag`通常为0

返回值:

1. 如果连接成功,返回MYSQL*连接句柄.如果连接失败,返回NULL.对于成功的连接,返回值与第1个参数的值相同.
2. 错误
    1. CR_CONN_HOST_ERROR 无法连接到MySQL服务器
    2. CR_CONNECTION_ERROR 无法连接到本地MySQL服务器
    3. CR_IPSOCK_ERROR 无法创建IP套接字
    4. CR_OUT_OF_MEMORY 内存溢出
    5. CR_SOCKET_CREATE_ERROR 无法创建Unix套接字
    6. CR_UNKNOWN_HOST 无法找到主机名的IP地址
    7. CR_VERSION_ERROR 协议不匹配
    8. CR_NAMEDPIPEOPEN_ERROR 无法在Windows平台下创建命名管道
    9. CR_NAMEDPIPEWAIT_ERROR 在Windows平台下等待命名管道失败
    10. CR_NAMEDPIPESETSTATE_ERROR 在Windows平台下获取管道处理程序失败
    11. CR_SERVER_LOST 如果`connect_timeout>0`,而且在连接服务器时所用时间长于`connect_timeout`秒,或在执行init-command时服务器消失.

mysql_real_query

原型: int mysql_real_query(MYSQL *mysql, const char *query, unsigned long length)
描述: 执行由query指向的SQL查询,length是字符串query的长度
返回值: 如果查询成功,返回0.如果出现错误,返回非0值.
错误:

  • CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令
  • CR_SERVER_GONE_ERROR MySQL服务器不可用
  • CR_SERVER_LOST 在查询过程中,与服务器的连接丢失
  • CR_UNKNOWN_ERROR 出现未知错误

mysql_store_result

原型: MYSQL_RES *mysql_store_result(MYSQL *mysql)
描述: 对于成功检索了数据的每个查询(SELECT、SHOW、DESCRIBE、EXPLAIN、CHECK TABLE等),必须调用mysql_store_result()mysql_use_result()获得返回结果集.mysql_store_result()将查询的全部结果读取到客户端,分配1个MYSQL_RES结构,并将结果置于该结构中.如果未返回行,将返回空的结果集.(空结果集设置不同于作为返回值的空指针)
返回值: 具有多个结果的MYSQL_RES结果集合.如果出现错误,返回NULL.
错误:

  1. 成功,mysql_store_result()将复位mysql_error()mysql_errno()
  2. 错误:
    • CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令
    • CR_OUT_OF_MEMORY 内存溢出
    • CR_SERVER_GONE_ERROR MySQL服务器不可用
    • CR_SERVER_LOST 在查询过程中,与服务器的连接丢失
    • CR_UNKNOWN_ERROR 出现未知错误

mysql_free_result

原型: void mysql_free_result(MYSQL_RES *result)
描述: 释放由mysql_store_result()mysql_use_result()mysql_list_dbs()等为结果集分配的内存.完成对结果集的操作后,必须调用mysql_free_result()释放结果集使用的内存.释放完成后,不要尝试访问结果集.
返回值: 无
错误: 无

mysql_field_count

原型: unsigned int mysql_field_count(MYSQL *mysql)
描述: 返回作用在连接上的最近一次查询结果集的列数.
返回值: 表示结果集中列数的无符号整数.
错误: 无.

mysql_num_fields

原型: unsigned int mysql_num_fields(MYSQL_RES *result)
描述: 返回结果集中的列数.
返回值: 表示结果集中列数的无符号整数.
错误: 无

mysql_fetch_fields

原型: MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)
描述: 对于结果集,返回所有MYSQL_FIELD结构的数组.每个结构提供了结果集中列的字段定义.
返回值: 关于结果集所有列的MYSQL_FIELD结构的数组.
错误: 无

mysql_num_rows

原型: my_ulonglong mysql_num_rows(MYSQL_RES *result)
m描述: 返回结果集中的行数.
返回值: 结果集中的行数.
错误: 无.

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_fetch_row

原型: MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)
描述: 检索结果集的下一行.在mysql_store_result()之后使用时,如果没有要检索的行,mysql_fetch_row()返回NULL;在mysql_use_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_fetch_row()的两次调用之间,不会复位错误.

  • CR_SERVER_LOST 在查询过程中,与服务器的连接丢失
  • CR_UNKNOWN_ERROR 出现未知错误

mysql_use_result

原型: MYSQL_RES *mysql_use_result(MYSQL *mysql)
描述: 对于成功检索数据的每个查询(SELECT、SHOW、DESCRIBE、EXPLAIN),必须调用mysql_store_result()mysql_use_result().mysql_use_result()将初始化结果集检索,然后必须通过对mysql_fetch_row()的调用,对每一行分别进行检索.将直接从服务器读取结果,而不会将其保存在临时表或本地缓冲区内.使用mysql_use_result()时,必须执行mysql_fetch_row(),直至返回NULL值,否则,未获取的行将作为下一个检索的一部分返回.C API给出命令不同步错误,如果忘记了执行该操作,将不能运行该命令.不应与从mysql_use_result()返回的结果一起使用mysql_data_seek()mysql_row_seek()mysql_row_tell()mysql_num_rows()mysql_affected_rows(),也不应发出其他查询,直至mysql_use_result()完成为止,当提取了所有行后,mysql_num_rows()将准确返回提取的行数.一旦完成了对结果集的操作,必须调用mysql_free_result()
返回值: MYSQL_RES结果结构.如果出现错误,返回NULL.
错误:

  1. 如果成功,mysql_use_result()将复位mysql_error()mysql_errno().
  2. 错误:
    • CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令.
    • CR_OUT_OF_MEMORY 内存溢出.
    • CR_SERVER_GONE_ERROR MySQL服务器不可用.
    • CR_SERVER_LOST 在查询过程中,与服务器的连接丢失.
    • CR_UNKNOWN_ERROR 出现未知错误.

mysql_fetch_lengths

原型: unsigned long *mysql_fetch_lengths(MYSQL_RES *result)
描述: 返回结果集内当前行的列的长度(避免strlen()的调用,提高效率; 确定二进制数据长度). 对于空列以及包含NULL值的列,其长度为0.
返回值: 无符号长整数的数组表示各列的大小(不包括任何终结NULL字符).如果出现错误,返回NULL.
错误: mysql_fetch_lengths()仅对结果集的当前行有效.如果在调用mysql_fetch_row()之前或检索了结果集中的所有行后调用了它,将返回NULL.

mysql_affected_rows

原型: my_ulonglong mysql_affected_rows(MYSQL *mysql)
描述: 返回上次UPDATE更改的行数或上次DELETE删除的行数或上次INSERT语句插入的行数.对于UPDATEDELETEINSERT语句,可在mysql_query()后立刻调用.
返回值: 大于0的整数表明受影响或检索的行数.”0”表示UPDATE语句未更新记录,在查询中没有与WHERE匹配的行,或未执行查询.
错误: 无

mysql_autocommit

原型: my_bool mysql_autocommit(MYSQL *mysql, my_bool mode)
描述: 如果模式为1,启用autocommit模式;如果模式为0,禁止autocommit模式.
返回值: 如果成功,返回0;如果出现错误,返回非0值.
错误: 无

mysql_commit

原型: my_bool mysql_commit(MYSQL *mysql)
描述: 提交当前事务.
返回值: 如果成功,返回0;如果出现错误,返回非0值.
错误: 无

mysql_rollback

原型: my_bool mysql_rollback(MYSQL *mysql)
描述: 回滚当前事务
返回值: 如果成功,返回0;如果出现错误,返回非0值.
错误: 无

mysql_real_escape_string

原型: unsigned long mysql_real_escape_string(MYSQL *mysql, char *to, const char *from, unsigned long length)
描述: 该函数用于创建可在SQL语句中使用的合法SQL字符串.按照连接的当前字符集,将from中的字符串编码为转义SQL字符串.将结果置于to中,并添加1个终结用Null字符.
返回值: 置于to中的值的长度,不包括终结用Null字符.
错误: 无.

mysql_errno

原型: unsigned int mysql_errno(MYSQL *mysql)
描述: 对于由mysql指定的连接,mysql_errno()返回最近调用的API函数的错误代码,该函数调用可能成功也可能失败.0返回值表示未出现错误.
返回值: 如果失败,返回上次mysql_xxx()调用的错误代码.0表示未出现错误
错误: 无

mysql_error

原型: const char *mysql_error(MYSQL *mysql)
描述: 对于由mysql指定的连接,对于失败的最近调用的API函数,mysql_error()返回包含错误消息的、由Null终结的字符串.如果该函数未失败,mysql_error()的返回值可能是以前的错误,或指明无错误的空字符串.
返回值: 返回描述错误的、由Null终结的字符串.如果未出现错误,返回空字符串.
错误: 无.