MySQL-部分C API解读

 C API提供对MySQL 客户端/服务器 低级访问,使得C程序能够访问MySQL数据库中的内容.C API代码是和MySQL一起发布的,并在libmysqlclient库中进行实现.可参考27.8.1节 MySQL C API实现.大多数的客户端API使用libmysqlclient库与MySQL服务器进行通信(Connector/J Connector/Net除外).这意味着,您可以利用其他客户端程序而使用相同的环境变量,因为他们都是libmysqlclient的引用.可在4.1节 MySQL概述中获取这些变量的列表.

        有关C API构建客户端程序的相关说明可查看27.8.4.1节构建C API客户端程序.有关多线程编程,可查看27.8.4.3基于C API编写多线程客户端程序.要在统一程序中创建包含服务器客户端的独立应用(不与外部的MySQL服务器通信),可参考27.7节 libmysqld,嵌入式MySQL服务器库.

注意:

        如果在升级后,遇到了编译的客户端程序问题,例如命令不同步或者unexpect core dumps,则此程序可能是使用旧版本的头文件和库文件进行编译的.在这种情况下,需要检查用于编译的mysql.h和libmysqlclient.a库的日期,以验证是否来自新的MySQL发行版.如果不是,请使用最新的头文件和库重新编译程序.如果库的朱版本号改变(例如从libmysqlcilet.so.17到libmysqlcilet.so.18),使用共享库的程序也需要重新编译,有关其他建荣信息,可参看27.8.4.4节 运行 C API客户端程序.

    客户端具有最大的通信缓冲区,最初分配的缓冲区大小是16KB会自动增加到最大的16MB. 因为缓冲区大小仅在需求保证时增加,所以简单的增加最大限制本身不会使用更多的资源.此大小的检查主要是针对错误语句和通信包的预防措施.

    通信缓冲区必须足够大,以包含单个SQL语句(用于client到server的数据流量)和一行返回数据(server到client的数据流量).每个回话的通信缓冲区都会动态放大,以处理任何查询直到最大限制.例如,如果您的BL0B值包含16MB数据,则必须具有至少16MB的通信缓冲区限制(server,client中都要有).客户端中内置的默认值最大值是1GB,但服务器中默认最大值是1MB.你可以再服务器启动时更改max_allowed_packet参数来增加此值.详细可参考5.1.1节配置服务器.

        每次查询后MySQL服务器会将每个通信缓冲区缩小为net_buffer_length个字节,对于客户端,在链接关闭前,与链接关联的缓冲区大小不会减少,在链接关闭时,客户端负责回收内存.

C API数据结构

   本节介绍除预处理语句之外的C API数据结构.有关预处理的信息可参考27.8.9节 "C API预处理数据结构"

• MYSQL :此结构表示一个数据库链接的句柄.此结构几乎用于所有的MySQL函数.不要试图复制此结构,MySQL不保证复制后的此结构可用
• MYSQL_RES:   此结构代表返回以行为单位的查询结果(SELECT,SHOW,DESCRIBE,EXPLAIN).查询返回的信息是下面各章节中的结果集.
• MYSQL_ROW:这是一行数据的类型安全表示形式.其目前被实现为以字节技术的字符串数组(如果字段中含有二进制数据,则不能将这些视为以null结尾的字符串,因此此类值可能在内部包含null字节.).通常通过调用mysql_fetch_row()获取行数据.
• MYSQL_FIELD:此结构包含元数据信息(metadata):有关字段信息,字段名称,类型以及大小等.此结构的其他成员在后面详细介绍.你可以通过重复调用mysql_fetch_field()来获取每个字段的MYSQL_FIELD结构.字段值不是此结构的一部分,他们包含在MYSQL_ROW结构中.
• MYSQL_FIELD_OFFSET:这是MySQL字段列表中偏移量的类型安全表示.mysql_field_seek()函数使用MYSQL_FIELD_OFFSET.偏移量是一行中的字段编号,从0开始.
• my_ulonglong:此类型用于mysql_affected_rows(),mysql_num_rows()以及mysql_insert_id()多对应的行数,此类型值的范围是0---1.84e19.某些返回值类型是此类型函数利用返回-1,来表示错误或者异常情况.你可以通过将返回值与((my_ulonglong) -1 或者(my_ulonglong) ~0)比对来检测-1的情况.在某些系统上尝试打印my_ulonglong类型的值是无效的,要打印此类型的值,可将其转换为unsigned long long 并使用%lu进行打印:

  printf ("Number of rows: %lu\n",(unsigned long) mysql_num_rows(result));

• my_bool:bool类型用于表示true和false

    MYSQL_FIELD结构包含如下列表中描述的成员.这些定义主要适用于结果集的列,例如SELECT语句生成的列.MYSQL_FEILD结构还用于调用预处理语句过程中存储的返回的OUT以及传入的INOUT参数提供元数据.

typedef struct st_mysql_field {
  char *name;                 /* 列名称 */
  char *org_name;             /* 如果有别名的话忽略别名,是原始列名*/
  char *table;                /* (非计算)字段的表的名称.如果是计算字段,是空字符串 */
  char *org_table;            /* 如果table是别名的话,org_table是原始表名 */
  char *db;                   /* 数据库名称 */
  char *catalog;	      /* 表目录,始终是"def"字段值 */
  char *def;                  /* 字段默认值(使用mysql_list_fields()设置) */
  unsigned long length;       /* 列宽度,以字节为单位 */
  unsigned long max_length;   /* 所选集合的最大宽度 */
  unsigned int name_length;
  unsigned int org_name_length;
  unsigned int table_length;
  unsigned int org_table_length;
  unsigned int db_length;
  unsigned int catalog_length;
  unsigned int def_length;
  unsigned int flags;         /* 字段位标志 */
  unsigned int decimals;      /* 字段中小数位数 */
  unsigned int charsetnr;     /* 字符集 */
  enum enum_field_types type; /* 字段类型 */
  void *extension;
} MYSQL_FIELD;

C API函数概述

 一下列表总结了C API中部分常用函数,更多详细内容可参考 27.8.7 C API 函数说明.

• my_init():在线程安全的程序中初始化全局变量以及线程处理程序

  MYSQL *mysql_init(MYSQL *mysql);
  /*描述：
      为适用于mysql_real_connect()的MYSQL对象分配内存或者初始化MYSQL对象。如果mysql==NULL,则此函数创建一个MYSQL*对象并分配内存，初始化后返回初始化后对象的地址。如果mysql_init()分配一个新对象，则在调用mysql_close()关闭连接的时候释放该对象
      在非多线程的情况下，mysql_init()会根据需要自动调用mysql_library_init().但mysql_library_init()是非线程安全的，因此mysql_init()也是非线程安全的。在调用mysql_init()之前，要么在生成任何线程之前调用mysql_library_init()要么使用互斥锁来保护mysql_library_init()的调用。这应该在客户端调用客户端库之前完成。
  返回值:
      初始化过的MYSQL*对象，如果没有足够内存，则返回NULL
  错误:
      如果内存不足，返回NULL
  */

  mysql_affected_rows():返回上次UPDATE,DELETE,INSERT中受到影响的行数.

  my_ulonglong mysql_affected_rows(MYSQL *mysql);
  /*
  描述：
      在使用mysql_query()或者mysql_real_query()执行MySQL语句后，可以立即调用mysql_affected_rows()。如果最后一个语句是UPDATE,DELETE,INSERT，则其返回语句执行后受到影响的行号。对于SELECT来说，mysql_affected_rows()的工作方式与mysql_num_rows()类似。
      对于UPDATE语句，默认情况下受影响的行号是实际修改的行号，如果在连接到mysqld时指定了mysql_real_connect()的CLIENT_FOUND_ROWS标志，则受影响的行值是找到的行数。也就是由WHERE子句匹配。
      对于REPLACE语句，如果新行替换旧行，则affected-rows值为2，因为在这种情况下是在删除旧行后又插入了一行。
      对于INSERT...ON DUPLICATE KEY UPDATE语句，如果插入了新行则受影响的值是1，如果更新现有行则受影响的行值是2.如果将现有行设置为当前行则受影响值是0.如果指定了CLIENT_FOUND_ROWS标志，则如果将现有行设置为当前值则受影响的行值是1不是0.
      在存储过程的CALL语句之后，mysql_affected_rows()返回存储过程中执行最后一个语句返回的值，如果最后一个语句返回-1，则mysql_affected_rows()返回0.在该过程中，你可以在SQL级别使用ROW_COUNT()来获取各个语句受影响的行值。
      在MySQL5.7中，mysql_affected_rows()为更广泛的语句返回有意义的值。
  返回值：
      >0:表示受影响或者检索的行数
      =0:没有为UPDATE语句更新记录，没有与查询中的WHERE子句匹配的行或者尚未执行任何查询
      -1:表示查询返回错误。或者对于SELECT，在调用mysql_store_result()之前调用了mysql_affected_rows()
      因为mysql_affected_rows()返回无符号值，所以可以通过将返回值与(my_ulonglong)-1或者(my_ulonglong)~0来检查-1的情况
  错误：
  */
  //例子：
  char *stmt = "UPDATE products SET cost=cost*1.25 WHERE group=10";
  mysql_query(&mysql,stmt);
  printf("%ld products updated",(long) mysql_affected_rows(&mysql));

   

• mysql_autocommit():打开关闭自动提交模式
• mysql_change_user():更改打开的链接上的用户和数据库
• mysql_character_set_name():返回当前链接的默认字符集名称
• mysql_client_find_plugin():返回插件指针
• mysql_client_register_plugin():注册插件
• mysql_close():关闭服务器链接
• mysql_commit():提交事物
• mysql_connect():链接MySQL服务器,不推荐使用此功能,请修改为mysql_real_connect()
• mysql_create_db():创建一个数据库,不推荐使用此功能,请改用SQL语句 CRETE DATEBASE
• 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函数的错误信息

  const char *mysql_error(MYSQL *mysql);
  /*
  描述：
     对于mysql指定的链接，mysql_error()返回一个以null结尾的字符串，其中包含最近调用的API函数的错误消息，如果函数没有失败，则mysql_error()的返回值可能是之前的错误或者是空字符串表示没有错误。根据经验所有必须要求服务器提供信息的函数如果成功则重置mysql_error().对于重置mysql_error()的函数，可使用一下两个测试中任何一个来检查错误:
     if(*mysql_error(&mysql))
  {
    // an error occurred
  }
  if(mysql_error(&mysql)[0])
  {
    // an error occurred
  }
  可以通过重新MySQL客户端库来更改客户端错误消息的语言。您可以选择多种不同的语言的错误消息。
  返回值：以null结尾的描述错误信息的字符串。如果没有错误，则返回空字符串
  错误：无
  */

    

• mysql_escape_string():转义字符串中的特殊字符以用于SQL语句
• mysql_fetch_field():返回下一个表字段类型

  MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result);
  /*
  描述：
      将结果集中的一列数据定义为MYSQL_FIELD结构返回。重复调用此函数以检索有关结果集中的所有列的信息。当没有剩余字段的时候，mysql_fetch_filed()返回NULL。每次执行新的SELECT查询时，mysql_fetch_field()都会重置以返回有关第一个字段的信息。mysql_fetch_field()返回的字段也会受到mysql_field_seek()的影响。
      如果你调用了mysql_query()来对表执行SELECT操作但是没有调用mysql_store_result()。那么如果调用mysql_fetch_field()会询问BLOB字段的长度，MySQL将返回默认的blob长度(8KB).(选择8KB大小是因为MySQL不知道BLOB的最大长度。这应该是可以配置的。)一旦检索返回了结果集，field->max_length包含该列中最大值的长度。
  返回值：
      返回结果集当前列的MYSQL_FIELD结构，如果没有当前列则返回NULL
  错误：无
  */
  //示例
  MYSQL_FIELD *field;
  while((field = mysql_fetch_field(result)))
  {
      printf("field name %s\n", field->name);
  }

   

• mysql_fetch_filed_direct():给定一个字段编号,返回表字段的类型
• mysql_fetch_fileds():返回所有字段结果数组.
• mysql_fetch_lengths():返回当前行中的所有列长度

  unsigned long *mysql_fetch_lengths(MYSQL_RES *result);
  /*
  描述：
      返回结果集中当前行的列宽度。如果你计划复制字段值，则此长度信息对于优化十分有用，因为使用此函数后，你可以避免调用strlen()函数。此外如果结果集中包含二进制数据，则必须使用此函数来确定数据大小，因为strlen会在空字符处截止以至于返回不正确的字段宽度。空列或者包含NULL的值列其返回的长度是0.
  返回值：
      表示每列大小的无符号的长整形数组(不包括任何终止空字节)，如果发生错误返回NULL
  错误：
      mysql_fetch_lengths()仅对结果集的当前行有效，如果在调用mysql_fetch_row()之前或在检索结果中的所有行之后调用它将返回NULL.
  */
  //示例：
  MYSQL_ROW row;
  unsigned long *lengths;
  unsigned int num_fields;
  unsigned int i;
  row = mysql_fetch_row(result);
  if (row)
  {
      num_fields = mysql_num_fields(result);
      lengths = mysql_fetch_lengths(result);
      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_fetch_row()检索结果集的下一行数据。当使用mysql_store_result()或mysql_use_result()后，如果没有结果集中没有剩余行或者发生错误则mysql_fetch_row()返回NULL.数据行中的值的数量由mysql_num_fields()给出。如果row保存了mysql_fetch_row()返回的值，则可访问的值范围是row[0]--row[mysql_num_fields(result)-1];即一行中的数据个数是mysql_num_fields(result)的返回值。NULL指针表示行中的NULL值。
      可使用mysql_fetch_lengths()来获取行中字段值的长度。空字段和包含NUL的字段的长度都是0;你可以通过检查字段值的指针来区分。如果指针是NULL，则字段是NULL.否则该字段为空
  返回值:
      下一行数据的MYSQL_ROW结构。或是NULL。NULL返回的含义取决于mysql_fetch_row()之前调用的函数。在mysql_store_result()或mysql_use_result()之后调用，如果没有要检索的行或者发生错误则mysql_fetch_row()返回NULL.要确定是否发生错误，请检查mysql_error()是返回空字符串或者mysql_errno()返回非0值。
  错误：
      调用mysql_fetch_row()不会重置错误。
      CR_SERVER_LOST:查询期间与服务器断开链接
      CR_UNKNOWN_ERROR:未知错误
  */
  //示例：
  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_errno(…&mysql)来替换mysql_field_count(&mysql)。在这种情况下，您直接检查mysql_store_result()中的错误，而不是从mysql_field_count()的返回值来推断该语句是否是SELECT.
  返回值：无符号整形数，病史查询到的结果集的列数
  错误：
  */
  //示例
  MYSQL_RES *result;
  unsigned int num_fields;
  unsigned int num_rows;
  
  if (mysql_query(&mysql,query_string))
  {
      // error
  }
  else // query succeeded, process any data returned by it
  {
      result = mysql_store_result(&mysql);
      if (result)  // there are rows
      {
          num_fields = mysql_num_fields(result);
          // retrieve rows, then call mysql_free_result(result)
      }
      else  // mysql_store_result() returned nothing; should it have?
      {
          if(mysql_field_count(&mysql) == 0)
          {
              // query does not return data
              // (it was not a SELECT)
              num_rows = mysql_affected_rows(&mysql);
          }
          else // mysql_store_result() should have returned data
          {
              fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
          }
      }
  }

• mysql_field_seek():将列光标放在指定的列上
• mysql_field_tell():返回用于最后一个mysql_fetch_field()字段的光标位置
• mysql_free_result():释放结果集使用的内存
• mysql_get_character_set_info():返回有关默认字符串集的信息
• mysql_get_client_info():以字符串的形式返回客户端的版本信息
• mysql_get_client_version():以整数形式返回客户端版本信息
• 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():返回与简单的正则表达式匹配的数据库名称
• mysql_list_fields():返回与简单正则表达式相匹配的字段名称
• mysql_list_processes():返回当前服务器线程列表
• mysql_list_tables():返回与简单正则表达式匹配的表名
• mysql_load_plugin():加载一个插件
• mysql_load_plugin_v():加载插件
• mysql_more_result():检查是否存在更多结果
• mysql_next_result():返回/启动多结果执行的下一个结果
• mysql_num_fields():返回结果集中的列数

  unsigned int mysql_num_fields(MYSQL_RES *result);
  /*
  要传递MYSQL*参数使用unsigned int mysql_field_count(MYSQL* mysql)
  描述:
      返回结果集中的列数。你可以从指向结果集的指针(MYSQL_RES *)或(MYSQL*)获取结果集列数。如果mysql_store_result()或mysql_use_result()返回NULL(没有结果集指针)，你可以调用mysql_field_count()来确定mysql_store_result()是否产生非空结果集。这使得客户端程序能够在不知道查询是否是SELECT(或类似SELECT)语句的情况下采取适当操作。此处示例说明了如下操作：
  返回值：
      表示结果集中列数，是一个无符号整数
  错误：
      无
  */
  //示例：
  MYSQL_RES *result;
  unsigned int num_fields;
  unsigned int num_rows;
  if (mysql_query(&mysql,query_string)){
      // error
  }else {
      // query succeeded, process any data returned by it
      result = mysql_store_result(&mysql);
      if (result){
          // there are rows
          num_fields = mysql_num_fields(result);
          // retrieve rows, then call mysql_free_result(result)
      }else {
          // mysql_store_result() returned nothing; should it have?
          if (mysql_errno(&mysql))
          {
             fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
          }else if (mysql_field_countmysql_field_count(&mysql) == 0)
          {
              // query does not return data
              // (it was not a SELECT)
              num_rows = mysql_affected_rows(&mysql);
          }
      }
  }

• mysql_num_rows():返回结果集中的行数

  my_ulonglong mysql_num_rows(MYSQL_RES *result);
  /*
  描述：
      返回结果集中的函数。mysql_num_rows()的使用取决于你是使用的mysql_store_result()还是mysql_next_result()来返回结果集的。如果使用的是mysql_store_result()则可以立即调用mysql_num_rows()来获取结果集的行数。如果使用的是mysql_use_result()，则在检索结果集所有行之前，mysql_num_rows()是不会返回正确的值的。mysql_num_rows()旨在返回结果集的语句例如SELECT.对于INSERT,UPDATE,DELETE等语句，可以使用mysql_affected_rows()来获取受影响的行数。
  返回值：返回结果集中是行数
  错误：无
  */

• MYSQL_RES *mysql_store_result(MYSQL *mysql)():为mysql_real_connect()设置链接选项.
• mysql_options4():为mysql_real_connect()设置链接选项
• mysql_ping():检查与服务器的链接是否正常,必要时重连
• mysql_plugin_options():设置一个插件选项
• mysql_query():执行一个SQL查询

  int mysql_query(MYSQL *mysql, const char *stmt_str);
  /*
  描述：
      执行以null结尾的SQL语句字符串stmt_str.通常字符串必须是单个MySQL语句，不带终止分号“；”。如果已经启用了多语句执行，则该字符串可以包含由分号分隔的多个语句。mysql_query()不能用于包含二进制数据的语句，如果数据中包含二进制数据则必须使用mysql_real_query().如果你想知道语句是否返回了结果集，可以使用mysql_field_count()来检查。
  返回值：
      执行成功返回0，执行失败返回负数。
  错误：
      CR_COMMANDS_OUT_OF_SYNC:命令以不正确的顺序执行
      CR_SERVER_GNOME_ERROR:MySQL 服务器已经丢失
      CR_SERVER_LOST:在查询过程中与服务器的链接断掉了
      CR_UNKNOWN_ERROR:未知错误
  */

• mysql_real_connect():链接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_real_connect()尝试连接到在主机上运行的MySQL数据库引擎。mysql_real_connect()必须运行成功后才能执行其他需要MYSQL结构的API函数。
  参数:
      mysql:使用由mysql_init初始化过的MYSQL结构。你可以使用mysql_options()调用更改许多其他链接选项。
      host:可以是主机名或者IP地址。
           host=NULL或者host=localhost,则假定与本地主机连接，在windows上如果server使用了共享内存连接，则客户端使用共享内存与server进行链接；在Unix上客户端使用socket进行链接，unix_socket参数或者MYSQL_UNIX_PORT环境变量可用于指定socket名称。在windows上如果host="."或者未启用TCP/IP且未指定unix_socket或者host=NULL,如果server启用了有名管道，则客户端使用有名管道进行链接；如果server未启用有名管道，则发生错误，否则发生错误。
           可以通过设置MYSQL_OPT_PROTOCOL或者MYSQL_OPT_NAME_PIPE选项来决定要使用的链接类型，但是前提是server必须支持这些链接类型。
      user:是用户登录MySQL的用户名，如果user是空字符串或者NULL,则假定使用当前用户，在unix下当前用户就是当前登录系统的登录名，在windows ODBC下，必须显示指定当前用户名。
    passwd:登录MySQL的用户密码。如果passwd=NULL,则检查用户表中查找具有空密码字段的用户是否匹配。这使得数据库管理员能够以这样的方式设置MySQL权限系统，即用户根据他们是否指定了密码来获取不同的权限。
            注意：在调用mysql_real_connect()之前，不要尝试加密密码，密码加密是由客户端API自动实现的。
            user和passwd使用为MYSQL配置的任何字符集。默认情况下是latin1字符集，但是可以通过在连接之前调用mysql_options(mysql,MYSQL_SET_CHARSET_NAME,"charset_name")来更改。
        db:数据库名称，如果db不为NULL,则连接会将缺省数据库设置为db所代表的数据库。
        port:如果port不为0，则该值将作为TCP/IP连接的端口号，需要注意的是host参数确定连接的类型。
  unix_socket:如果unix_socket不为NULL,则字符串指定的要使用的socket或命名管道，需要注意的是host参数确定连接类型
  client_flag:通常为0，但可以设置以下标志的组合以启用某些功能。
              CAN_HANDLE_EXPIRED_PASSWORDS:客户端可以处理过期的密码
              CLIENT_COMPRESS:在客户端/服务器协议中使用压缩
              CLIENT_FOUND_ROWS:返回找到匹配函数，而不是已经更改的行数
              CLIENT_IGNORE_SIGPIPE:组织客户端库安装SIGPIPE信号处理程序，可用于避免与已安装应用程序的处理程序冲突
              CLIENT_IGNORE_SPACE:允许函数名后面的空格，
              CLIENT_INTERACTIVE:在关闭连接之前，允许interactive_timeout秒不活动，客户端会话在wait_timeout变量设置为会话的interactive_timeout变量的值。
              CLIETN_LOCAL_FILLES:启用LOAD DATA LOCAL处理
              CLIENT_MULTI_RESULTS:如果启用的话告诉服务器，客户端可以处理来自多条语句执行或存储过程的多个结果集。如果启用了CLIENT_MULTI_STATEMENTS则会自动启用CLIENT_MULTI_RESULTS。
              CLIENT_MULTI_STATEMENTS:告知服务器，客户端可以在一个字符串中通过";"分隔发送多条语句。如果未设置此标志，则禁用多语句执行。
              CLIENT_NO_SCHEMA:不允许db_name,tbl_name,col_name语法。这是针对ODBC的。如果使用该语法可能会导致解析器生成错误，对于捕获ODBC程序错误有用。
              CLIENT_ODBC:无用
              CILENT_SSL:使用SSL加密协议，不要在应用程序中设置此选项。他是在客户端库内部设置的。相反在调用mysql_real_connect()之前使用mysql_options()或mysql_ssl_set().
              CLIENT_REMEMBER_OPTIONS:记住调用mysql_options()指定的选项。如果没有此选项，如果mysql_real_connect()失败，则必须在尝试再次连接之前重复调用mysql_options()使用此选项则不必重复调用mysql_options.
              如果程序使用CALL语句执行存储过程，则必须启用CLIENT_MULTI_RESULTS标志。这是因为除了过程中执行的语句可能返回的任何结果集之外，每个CALL都返回一个结果来指示调用状态。因为CALL可以返回多个结果，所以循环调用mysql_next_result()来处理以确定是否有更多结果。
              调用mysql_real_connect()时启用CLIENT_MULTI_RESULTS的时候可以通过传递CLIENT_MULTI_RESULTS标志显示调用，也可以传递CLIENT_MULTI_STATEMENTS来隐式调用。在MySQL5.7默认是启用CLIENT_MULTI_RESULTS.
              如果启用CLIENT_MULTI_STATMENTS或CLIENT_MULTI_RESULTS，可通过循环调用mysql_next_result()来处理每次调用mysql_query()或者mysql_real_query()的结果，以确定是否有更多的结果。
              对某些参数，可以从选项文件中中获取值，而不必从mysql_real_connect()的显示调用中传入值。为此请在调用mysql_real_connect()之前使用MYSQL_READ_DEFAULT_FILE或者MYSQL_READ_DEFAULT_GROUP选项调用mysql_options.然后在调用mysql_readl_connect()时设置“no-value”的参数会从选项文件中读取值。
              host:指定NULL或空字符串“”
              user:指定NULL或空字符串“”
              passwd:指定NULL，对于密码来说，mysql_real_connect()调用中的空字符串的值不能在选项文件中重写，因为空字符串明确表明MySQL账户具有空密码
              db:指定NULL或空字符串“”
              port:指定0
              unix_socket:指定NULL
              如果在参数的选项文件中未找到任何值，则使用其默认值。
  返回值：
      如果连接成功，返回MYSQL*结构指针，即同mysql参数。如果连接失败返回NULL.
  错误：   
      CR_CONN_HOST_ERROR:连接到MySQL服务器失败
      CR_CONNECTION_ERROR:连接到本地MySQL服务器失败
      CR_IPSOCK_ERROR:创建IP socket失败
      CR_OUT_OF_MEMORY:内存不足
      CR_SOCKET_CREATE_ERROR:创建Unix socket失败
      CR_UNKNOWN_HOST:找不到主机名对应的IP地址
      CR_VERSION_ERROR:尝试使用不同协议版本的客户端连接服务器导致协议不匹配
      CR_NAMEDPIPEOPEN_ERROR:在windows上创建有名管道失败
      CR_NAMEDPIPEWAIT_ERROR:在windows上等待有名管道失败
      CR_NAMEDPIPESTATE_ERROR:在windows上获取有名管道句柄失败
      CR_SERVER_LOST:如果connect_timeout>0并且在连接服务器花费的时间超过了connect_timeout秒，或者执行init_command时服务器死机。
      CR_ALREADY_CONNECTED:MYSQL结果指针已经连接到了MySQL服务器
                
  */
  MYSQL mysql;
  mysql_init(&mysql);
  mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name");
  if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
  {
      fprintf(stderr, "Failed to connect to database: Error: %s\n",
            mysql_error(&mysql));
  }
  /*通过使用mysql_options(),MySQL客户端库读取my.cnf文件中的[client]和[your_prog_name]部分，确保程序正常工作。连接后，mysql_real_connect()在早于5.0.3的API版本中将重新连接标志(MYSQL结构的一部分)设置为1，在较新版本中此标志设置为0.此重新连接标志为1表示如果由于连接丢失而无法执行MySQL语句,则在放弃执行语句之前会再次尝试连接到服务器。可以使用mysql_options()设置MYSQL_OPT_RECONNECT选项来控制重新连接行为。
  
  */

• mysql_real_escape_string():转义字符中的特殊字符,以便在SQL语句中使用,同时考虑链接当前的字符集
• mysql_real_escape_string_quote():转义字符中的特殊字符,以便在SQL语句中使用,同时考虑链接当前的字符集和引用上下文
• mysql_real_query():执行指定计数字符串的SQL查询
• mysql_refresh():刷新或重置表和缓存
• mysql_reload():告诉服务器重新加载授权表
• mysql_reset_connection():重置链接以清除会话状态
• mysql_rollback():回滚事务
• mysql_row_seek():使用从mysql_row_tell()返回的值,在结果集中国寻找行偏移量
• mysql_row_tell():返回行光标位置
• mysql_select_dn():选择数据库
• 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():设置LOAD DATA LOCAL回调处理程序设置为默认值
• mysql_local_infile_handler():安装特定应用程序的LOAD DATA LOCAL回调处理函数
• mysql_set_server_option():设置链接选项
• mysql_sqlstate():返回上一个错误的SQLSTATE错误代码
• mysql_shutdown():关闭数据库服务器
• mysql_ssl_set():准备与服务器建立SSL链接
• mysql_stat():以字符串的形式返回服务器状态
• mysql_store_result():检索客户端的完整结果集

  MYSQL_RES *mysql_store_result(MYSQL *mysql);
  /*
  描述：
      在调动mysql_query()或者mysql_real_query()后，必须为每个成功生成结果集的语句(SELECT,SHOW,DESCRIBE,EXPLAIN,CHECK TABLE等)调用mysql_store_result或mysql_use_result.完成结果集后还必须调用mysql_free_result().其他语句不需要调用mysql_store_result()或mysql_use_result(),但是在任何情况下都调用也不会有什么危害，也不会带来性能的下降。可以检测mysql_store_result的返回值是否为非零值来检测是否得到结果集。
       如果启用了多语句支持，则应该通过循环调用mysql_next_result()来检索mysql_query()或者mysql_real_query()的结果，以确定是否有更多结果。如果你想知道语句是否应该返回结果集，可以使用mysql_fiels_count()来检查。
       mysql_store_result()将查询的整个结果都读取到客户端，并分配MYSQL_RES结构，将结果存储在此结构中。如果MySQL语句未返回结果集(例如INSERT语句)，则mysql_store_result()返回NULL。或者发生错误且读取结果集失败。
       如果MySQL语句执行没有行数据返回，则返回空的结果集(空结果集与空指针的区别在于返回值。)空结果集其返回结果不是NULL。在调用mysql_store_result()且返回不是NULL的结果后，可调用mysql_num_rows()查找结果集中有多少行。
       可以调用mysql_fetch_row()从结果集中获取行数据，或者调用mysql_row_seek()和mysql_row_tell()以获取或设置结果集中的当前行位置。
  返回值：
      指向具有结果的MYSQL_RES结构指针。如果语句未返回结果集或者发生错误，则返回NULL.要确定是否发生错误，需要调用mysql_error()来获取错误信息或者调用mysql_errno()来获取错误码，或者mysql_field_count()返回0
  错误：
      mysql_store_result()如果成功则重置mysql_error()和mysql_errno()。
      CR_COMMANDS_OUT_SYNC:命令以不正确的顺序执行
      CR_OUT_OF_MEMORY:内存不足
      CR_SERVER_GONE_ERROR:MySQL服务器消失
      CR_SERVER_LOST:查询期间与服务器断开链接
      CR_UNKNOWN_ERROR:未知错误
  mysql_num_fields*/

  

   

• • mysql_thread_end():完成一个线程处理程序
  • mysql_thread_id():返回当前线程id
  • mysql_thread_init():初始化线程处理程序
  • mysql_thread_safe():如果客户端编译为线程安全则返回1
  • mysql_use_result():启动逐行结果集检索
  • mysql_warning_count():返回上一个SQL语句的警告计数

      应用程序应该按照下面的大致流程与MySQL进行交互.

  1. 通过调用mysql_library_init()初始化MySQL客户端库.此函数存在于libmysqlclient C客户端库以及libmysqld嵌入式服务器库中,因此无论您是通过链接-lmysqlclient库还是链接-lmysqld(嵌入式)都可构建常规的客户端程序.
  2. 通过调用mysql_init()来初始化链接程序,并调用mysql_real_connect()链接到服务器.
  3. 发出SQL语句并处理结果
  4. 调用mysql_close()关闭与服务器的链接
  5. 调用mysql_libray_end()结束MySQL客户端库的使用.

      调用mysql_library_init()和mysql_library_end()的目的是提供MySQL客户端库的正确初始化和最终化.对于与客户端库链接的应用程序,他们提供了改进的内存管理机制.如果你不调用mysql_library_end(),虽然不会增加应用程序使用的内存数量,但是某些内存泄露工具会检测到内存泄露.对于嵌入式应用来说,这两个函数会启动关闭服务器.

      在非多线程的情况下,可以省略对mysql_library_init()的调用,因为mysql_init()会根据需要自定调用它.但是,mysql_library_init()在多线程环境中不是线程安全的,因此你必须在产生任何线程之前调用mysql_library_init()或者通过mysql_init()间接调用都需要使用互斥锁来保护调用.这些应该在调用任何客户端库函数之前完成.

      要链接到服务器,需要先调用mysql_init()初始化MYSQL句柄.,然后使用此句柄,主机名,用户名,密码等来调用mysql_real_connect().链接完成后,mysql_real_connect()在早于5.0.3的API版本中将重新链接标志(MYSQL结构一部分)设置为1,或者在新版本中设置为0.此标志值为1表示如果由于链接丢失而无法执行语句,则在放弃之前会尝试重新链接服务器.您可以调用mysql_options()的MYSQL_OPT_RECONNECT选项来控制重新链接行为.完成链接后,调用mysql_close()来终止链接,关闭后就不能在使用MYSQL句柄.

      当链接处于活跃状态时,客户端可以调用mysql_query()或者mysql_real_query()将SQL发送到服务器.两者之间的区别在于mysql_query()期望将查询指定为以null结尾的字符串,而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_query()或者(mysql_real_query())之后调用mysql_store_result()来完成此操作.如果结果集调用成功,则该语句是SELECT,您可以读取行.如果结果集调用失败,请调用mysql_field_count()以确定结果实际上预期的.如果mysql_field_count()返回0.则该语句不返回任何数据(表名它是INSERT,UPDATE,DELETE等),并且不会返回行/如果mysql_field_count()返回非0,.则该语句返回行,但没有则表名该语句是一个失败的SELECT.有关如何执行此操作的示例,可参考mysql_field_count()的说明.

      mysql_store_result()和mysql_use_result()都可以获取有关组成字符集字段的相关信息(字段数,名称,类型等等).你可以重复调用mysql_fetch_field()或通过调用mysql_fetch_field_direct()在行中的字段编号顺序访问行中的字段信息.可以通过调用mysql_filed_seek()来更改当前字段光标位置.设置光标位置会影响对mysql_fetch_field()的后续调用.你也可以调用mysql_fetch_fields()一次获取所有的字段信息.

         为了检测和报告错误,MySQL通过mysql_errno()和mysql_error()函数提供对错误信息的访问.这些函数返回最近调用的可能成功或失败的函数的错误代码或者错误信息,以便您能够确定错误发生的时间和错误原因.