MYSQL C API 学习汇总

MYSQL C API 学习汇总

1.查询结果集

(1)数据结构

typedef struct st_mysql_res {

  my_ulonglong 　　row_count;                              // 结果集的行数  (long或long long)

  unsigned 　　intfield_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 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_mysql_data {   my_ulonglong　　 rows;   unsigned int　　 fields;   MYSQL_ROWS *　　data;   MEM_ROOT　　 alloc; } MYSQL_DATA; // 数据集的结构   typedef struct st_mysql_rows {   struct st_mysql_rows *next;　　/* list of rows */   MYSQL_ROW data; } MYSQL_ROWS;        //mysql的数据的链表节点。可见mysql的结果集是链表结构   typedef char **    MYSQL_ROW;　　/* 返回的每一行的值，全部用字符串来表示*/  

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 　　intmin_malloc;

  unsigned　　 intblock_size;

  void (*error_handler)(void);

} MEM_ROOT;  //内存结构

(2)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()进行检查

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。

 4.mysql_num_rows

my_ulonglong mysql_num_rows(MYSQL_RES *result)

mysql_num_rows()的使用取决于是否采用了mysql_store_result()或mysql_use_result()来返回结果集。如果使用了mysql_store_result()，可以立刻调用mysql_num_rows()。如果使用了mysql_use_result()，mysql_num_rows()不返回正确的值，直至检索了结果集中的所有行为止。

5.mysql_num_fields

unsigned int mysql_num_fields(MYSQL_RES *result)

你可以从指向结果集的指针或指向连接句柄的指针获得行数。如果mysql_store_result()或mysql_use_result()返回NULL，应使用连接句柄（因而没有结果集指针）。在该情况下，可调用mysql_field_count()来判断mysql_store_result()是否生成了非空结果。这样，客户端程序就能采取恰当的行动，而不需要知道查询是否是SELECT语句（或类似SELECT的语句）。在下面的示例中，介绍了执行该操作的方式。

6.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。