MYSQL API以及基本操作介绍以及，MYSQL_FIELD介绍

一.mysql 常用基本结数据构介绍

typedef struct st_mysql_res {

  my_ulonglong row_count;                               // 结果集的行数

  unsigned int field_count, current_field;            // 结果集的列数，当前列

  MYSQL_FIELD *fields;                                    // 结果集的列信息

  MYSQL_DATA *data;                                      // 结果集的数据

  MYSQL_ROWS *data_cursor;                        // 结果集的光标

  MEM_ROOT field_alloc;                                   // 内存结构

  MYSQL_ROW row;                                         // 非缓冲的时候用到

  MYSQL_ROW current_row;                           //mysql_store_result时会用到。当前行

  unsigned long *lengths;                                //每列的长度

  MYSQL *handle;                                           // mysql_use_result会用。

  my_bool eof;                                                 //是否为行尾

} MYSQL_RES;

typedef char **MYSQL_ROW; /* 返回的每一行的值，全部用字符串来表示*/

typedef struct st_mysql_rows {

  struct st_mysql_rows *next; /* list of rows */

  MYSQL_ROW data;

} MYSQL_ROWS;        //mysql的数据的链表节点。可见mysql的结果集是链表结构

typedef struct st_mysql_data {

  my_ulonglong rows;

  unsigned int fields;

  MYSQL_ROWS *data;

  MEM_ROOT alloc;

} MYSQL_DATA; // 数据集的结构

typedef struct st_mysql_field {

  char *name; /* Name of column */

  char *table;                                            /* Table of column if column was a field */

  char *def;                                               /* Default value (set by mysql_list_fields) */

  enum enum_field_types type;                /* Type of field. Se mysql_com.h for types */

  unsigned int length;                               /* Width of column */

  unsigned int max_length;                       /* Max width of selected set */

  unsigned int flags;                                  /* Div flags */

  unsigned int decimals;                            /* Number of decimals in field */

} MYSQL_FIELD;  //列信息的结构

typedef struct st_used_mem { /* struct for once_alloc */

  struct st_used_mem *next; /* Next block in use */

  unsigned int left; /* memory left in block  */

  unsigned int size; /* Size of block */

} USED_MEM; //内存结构

typedef struct st_mem_root {

  USED_MEM *free;

  USED_MEM *used;

  USED_MEM *pre_alloc;

  unsigned int min_malloc;

  unsigned int block_size;

  void (*error_handler)(void);

} MEM_ROOT;  //内存结构

二。常用API介绍

1. int mysql_query(MYSQL* mysql, const char* query) //查询函数，成功返回零，否则返回错误类型非零值。  
2.   
3. const char* mysql_error(MYSQL* mysql) //返回最近一次调用失败的错误消息（返回的是字符串消息）  
4.   
5. unsigned int mysql_errno(MYSQL* mysql) //返回最近一次调用失败的错误代号（返回的是数字代号）  
6.   
7. MySQL_RES* mysql_store_result(MYSQL* mysql) //将数据库中查询(mysql_query)得到的结果(集合)存放在MySQL_RES结构中
8. 
   
9. MySQL_RES* mysql_use_result(MYSQL* mysql) //将数据库中查询(mysql_query)初始化检索，以便于后面一行一行的读取结果集，而它本身并没有从服务器读取任何数据
   
10. 
    
11. unsigned int mysql_num_fields(MYSQL_RES* res) //返回结果集中的列的数目  
12.   
13. MYSQL_ROW* mysql_fetch_row(MYSQL_RES* res) //返回结果集(MYSQL_RES)的当前行的结果  
14.   
15. unsigned int mysql_num_rows(MYSQL_RES* res) //返回结果集中的行的数目  
16.   
17. unsigned long* mysql_fetch_lengths(MYSQL_RES* res) //返回结果集中各列的长度（可用于字符串拷贝，代替strlen函数）  
18.   
19. void mysql_close(MYSQL* mysql) //数据库使用完毕之后应该进行关闭  

对常用API 介绍下

1. . 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()或mysql_use_result()，但是如果在任何情况下均调用了mysql_store_result()，它也不会导致任何伤害或性能降低。通过检查mysql_store_result()是否返回0，可检测查询是否没有结果集（以后会更多）。

如果希望了解查询是否应返回结果集，可使用mysql_field_count()进行检查。请参见25.2.3.22节，“mysql_field_count()”。

mysql_store_result()将查询的全部结果读取到客户端，分配1个MYSQL_RES结构，并将结果置于该结构中。

如果查询未返回结果集，mysql_store_result()将返回Null指针（例如，如果查询是INSERT语句）。

如果读取结果集失败，mysql_store_result()还会返回Null指针。通过检查mysql_error()是否返回非空字符串，mysql_errno()是否返回非0值，或mysql_field_count()是否返回0，可以检查是否出现了错误。

如果未返回行，将返回空的结果集。（空结果集设置不同于作为返回值的空指针）。

一旦调用了mysql_store_result()并获得了不是Null指针的结果，可调用mysql_num_rows()来找出结果集中的行数。

可以调用mysql_fetch_row()来获取结果集中的行，或调用mysql_row_seek()和mysql_row_tell()来获取或设置结果集中的当前行位置。

一旦完成了对结果集的操作，必须调用mysql_free_result()。

 

 

2. mysql_use_result()

MYSQL_RES *mysql_use_result(MYSQL *mysql)

描述

对于成功检索数据的每个查询（SELECT、SHOW、DESCRIBE、EXPLAIN），必须用mysql_store_result()或mysql_use_result()。

mysql_use_result()将初始化结果集检索，但并不像mysql_store_result()那样将结果集实际读取到客户端。它必须通过对mysql_fetch_row()的调用，对每一行分别进行检索。这将直接从服务器读取结果，而不会将其保存在临时表或本地缓冲区内，与mysql_store_result()相比，速度更快而且使用的内存也更少。客户端仅为当前行和通信缓冲区分配内存，分配的内存可增加到max_allowed_packet字节。

 

另一方面，如果你正在客户端一侧为各行进行大量的处理操作，或者将输出发送到了用户可能会键入“^S”（停止滚动）的屏幕，就不应使用mysql_use_result()。这会绑定服务器，并阻止其他线程更新任何表（数据从这类表获得）。

使用mysql_use_result()时，必须执行mysql_fetch_row()，直至返回NULL值，否则，未获取的行将作为下一个检索的一部分返回。C API给出命令不同步错误，如果忘记了执行该操作，将不能运行该命令。

不能对结果集用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。

 

3.取得一行的数据：

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已经连接好

 

MYSQL_RES* result = mysql_store_result(mysql);

 

if (result  == NULL)

  return;

 

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");

}

4. 取得列的信息。

mysql_fetch_field()

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

描述

返回采用MYSQL_FIELD结构的结果集的列。重复调用该函数，以检索关于结果集中所有列的信息。未剩余字段时，mysql_fetch_field()返回NULL。

每次执行新的SELECT查询时，将复位mysql_fetch_field()，以返回关于第1个字段的信息。调用mysql_field_seek()也会影响mysql_fetch_field()返回的字段。

如果调用了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);

}

5. 同4.

 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(result);

fields = mysql_fetch_fields(result);

for(i = 0; i < num_fields; i++)

{

   printf("Field %u is %s/n", i, fields[i].name);

}

6. 

 mysql_free_result()

void mysql_free_result(MYSQL_RES *result)

描述

释放由mysql_store_result()、mysql_use_result()、mysql_list_dbs()等为结果集分配的内存。完成对结果集的操作后，必须调用mysql_free_result()释放结果集使用的内存。

释放完成后，不要尝试访问结果集。

返回值

无。

永远记得要释放结果集！！！

三. MYSQL_FIELD 详细介绍

MYSQL

这个结构表示对一个数据库连接的句柄，它被用于几乎所有的MySQL 函数。

MYSQL_RES

这个结构代表返回行的一个查询的(SELECT , SHOW , DESCRIBE , EXPLAIN )的结果。从查询返回的信息在本章下文称为结果集合 。

MYSQL_ROW

这是一个行数据的类型安全(type-safe)的表示。当前它实现为一个计数字节的字符串数组。（如果字段值可能包含二进制数据，你不能将这些视为空终止串，因为这样的值可以在内部包含空字节) 行通过调用mysql_fetch_row() 获得。

MYSQL_FIELD

这个结构包含字段信息，例如字段名、类型和大小。其成员在下面更详细地描述。你可以通过重复调用mysql_fetch_field() 对每一列获得MYSQL_FIELD 结构。字段值不是这个结构的部分；他们被包含在一个MYSQL_ROW 结构中。

MYSQL_FIELD_OFFSET

这是一个相对一个MySQL 字段表的偏移量的类型安全的表示。（由mysql_field_seek() 使用。) 偏移量是在一行以内的字段编号，从0开始。

my_ulonglong

该类型用于行编号和mysql_affected_rows() 、mysql_num_rows() 和mysql_insert_id() 。这种类型提供0到1.84e19 的一个范围。在一些系统上，试图打印类型my_ulonglong 的值将不工作。为了打印出这样的值，将它变换到unsigned long 并且使用一个%lu 打印格式。例如：

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

 

MYSQL_FIELD 结构包含列在下面的成员：

char * name

字段名，是一个空结尾的字符串。

char * table

包含该字段的表的名字，如果它不是可计算的字段。对可计算的字段，table 值是一个空字符串。

char * def

这字段的缺省值，是一个空结尾的字符串。只要你使用，只有你使用mysql_list_fields() 才可设置它。

enum enum_field_types type

字段类型。type 值可以是下列之一：类型值类型含义FIELD_TYPE_TINYTINYINT 字段FIELD_TYPE_SHORTSMALLINT 字段FIELD_TYPE_LONGINTEGER 字段FIELD_TYPE_INT24MEDIUMINT 字段FIELD_TYPE_LONGLONGBIGINT 字段FIELD_TYPE_DECIMALDECIMAL 或NUMERIC 字段FIELD_TYPE_FLOATFLOAT 字段FIELD_TYPE_DOUBLEDOUBLE 或REAL 字段FIELD_TYPE_TIMESTAMPTIMESTAMP 字段FIELD_TYPE_DATEDATE 字段FIELD_TYPE_TIMETIME 字段FIELD_TYPE_DATETIMEDATETIME 字段FIELD_TYPE_YEARYEAR 字段FIELD_TYPE_STRING字符串(CHAR 或VARCHAR )字段FIELD_TYPE_BLOBBLOB 或TEXT 字段(使用max_length 决定最大长度）FIELD_TYPE_SETSET 字段FIELD_TYPE_ENUMENUM 字段FIELD_TYPE_NULLNULL - 类型字段FIELD_TYPE_CHAR不推荐；使用FIELD_TYPE_TINY 代替

你可以使用IS_NUM() 宏来测试字段是否有一种数字类型。将type 值传给IS_NUM() 并且如果字段是数字的，它将计算为TRUE：

if (IS_NUM(field->type))    printf("Field is numeric/n");

unsigned int length

字段宽度，在表定义中指定。

unsigned int max_length

对结果集合的字段的最大宽度(对实际在结果集合中的行的最长字段值的长度)。如果你使用mysql_store_result() 或mysql_list_fields() ，这包含字段最大长度。如果你使用mysql_use_result()，这个变量的值是零。

unsigned int flags

字段的不同位标志。flags 值可以是零个或多个下列位设置：标志值标志含义NOT_NULL_FLAG字段不能是NULLPRI_KEY_FLAG字段是一个主键的一部分UNIQUE_KEY_FLAG字段是一个唯一键的一部分MULTIPLE_KEY_FLAG字段是一个非唯一键的一部分。UNSIGNED_FLAG字段有UNSIGNED 属性ZEROFILL_FLAG字段有ZEROFILL 属性BINARY_FLAG字段有BINARY 属性AUTO_INCREMENT_FLAG字段有AUTO_INCREMENT 属性ENUM_FLAG字段是一个ENUM （不推荐）BLOB_FLAG字段是一个BLOB 或TEXT （不推荐）TIMESTAMP_FLAG字段是一个TIMESTAMP （不推荐）

BLOB_FLAG 、ENUM_FLAG 和TIMESTAMP_FLAG 标志的使用是不推荐的，因为他们指出字段的类型而非它的类型属性。对FIELD_TYPE_BLOB 、FIELD_TYPE_ENUM 或FIELD_TYPE_TIMESTAMP ，最好是测试field->type 。下面例子演示了一个典型的flags 值用法：

if (field->flags & NOT_NULL_FLAG)    printf("Field can't be null/n");

你可以使用下列方便的宏决来确定flags 值的布尔状态：

IS_NOT_NULL(flags)真，如果该字段被定义为NOT NULLIS_PRI_KEY(flags)真，如果该字段是一个主键IS_BLOB(flags)真，如果该字段是一个BLOB 或TEXT （不推荐；相反测试field->type ）

unsigned int decimals

对数字字段的小数位数。

20.4.14 mysql_fetch_field ()

MYSQL_FIELD *mysql_fetch_field (MYSQL_RES *result)

20.4.14.1 说明

返回作为一个MYSQL_FIELD 结构的一个结果集合的一个列的定义。重复调用这个函数在结果集合中检索所有关于列的信息。当没有剩下更多的字段时，mysql_fetch_field () 返回NULL 。

在每次你执行一个新的SELECT 查询，mysql_fetch_field () 被重置（reset)以返回有关第一列的信息。由mysql_fetch_field () 返回的字段也受调用mysql_field_seek() 的影响。

如果你调用mysql_query() 在一张表上执行一个SELECT ，但是没调用mysql_store_result() ，如果你调用mysql_fetch_field () 询问一个BLOB 字段的长度，MySQL 返回缺省BLOB长度(8K字节)。（选择8K的长度是因为MySQL 不知道BLOB 的最大长度。这应该在某个时候是它可配置) 一旦你已经检索了结果集合，field->max_length 包含了在特定查询中对于该列最大值的长度。

20.4.14.2 返回值

当前列的MYSQL_FIELD 结构。如果没有列剩下，NULL 。

20.4.14.3 错误

无。

20.4.14.4 范例

MYSQL_FIELD *field;while((field = mysql_fetch_field(result))){    printf("field name %s/n", field->name);} 

20.4.15 mysql_fetch_fields()

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)

20.4.15.1 说明

返回一个结果集合的所有MYSQL_FIELD 结构的数组。每个结构提供结果结合中一列的字段定义。

20.4.15.2 返回值

一个结果集合的所有MYSQL_FIELD 结构的一个数组。

20.4.15.3 错误

无。

 范例

unsigned int num_fields;unsigned int i;MYSQL_FIELD *fields;num_fields = mysql_num_fields(result);fields = mysql_fetch_fields(result);for(i = 0; i < num_fields; i++){   printf("Field %u is %s/n", i, fields[i].name);}