Mysql接口API相关函数详细使用说明——mysql_init,mysql_real_connect,mysql_query,mysql_close等相关

MySql接口API相关函数

1、部分API函数总览

1.1、部分API函数表

函数	作用描述
mysql_init()	获取或初始化MYSQL结构。
mysql_real_connect()	连接到MySQL服务器。
mysql_query()	执行指定为“以Null终结的字符串”的SQL查询。
mysql_store_result()	检索完整的结果集至客户端。
mysql_use_result()	初始化逐行的结果集检索
mysql_fetch_field()	返回下一个表字段的类型。
mysql_fetch_fields()	返回所有字段结构的数组。
mysql_fetch_lengths()	返回当前行中所有列的长度。
mysql_fetch_row()	从结果集中获取下一行
mysql_field_count()	返回上次执行语句的结果列的数目。
mysql_free_result()	释放结果集使用的内存。
mysql_close()	关闭服务器连接。
mysql_autocommit()	切换 autocommit模式，ON/OFF
mysql_commit()	提交事务。
mysql_errno()	返回上次调用的MySQL函数的错误编号
mysql_error()	返回上次调用的MySQL函数的错误消息
mysql_options()	为mysql_connect()设置连接选项。
mysql_ping()	检查与服务器的连接是否工作，如有必要重新连接。

1.2、部分MySql结构体说明

1、连接数据库前，必须先创建MYSQL变量，此变量在很多Mysql API函数会用到。它包含了一些连接信息等数据。

typedef struct st_mysql {
NET  net;            /* Communication parameters 通讯参数，网络相关*/
unsigned char connector_fd;   /* ConnectorFd for SSL 加密套接字协议层*/

char  *host,*user,*passwd,*unix_socket,*server_version,
*host_info,*info,*db;//数据库用户名，密码，主机名，Unix套接字，版本，主机信息

unsigned int  port,client_flag,server_capabilities;
unsigned int  protocol_version;
unsigned int  field_count;
unsigned int  server_status;
unsigned long thread_id;      /* Id for connection in server */
my_ulonglong affected_rows;
my_ulonglong insert_id;      /* id if insert on table with NEXTNR */
my_ulonglong extra_info;              /* Used by mysqlshow */
unsigned long packet_length;
enum mysql_status status;
MYSQL_FIELD   *fields;
MEM_ROOT      field_alloc;
my_bool       free_me;        /* If free in mysql_close */
my_bool       reconnect;      /* set to 1 if automatic reconnect */
struct st_mysql_options options;
char          scramble_buff[9];
struct charset_info_st *charset;
unsigned int  server_language;
} MYSQL;

2、MYSQL_RES结构体中包含了查询结果集，也就是从数据库中查询到的数据。可以使用mysql_store_result或mysql_use_result函数获得。这个结构代表返回行的一个查询的(SELECT, SHOW, DESCRIBE, EXPLAIN)的结果。返回的数据称为“数据集”，在C的API里对应的就是MYSQL_RES，从数据库读取数据，最后就是从MYSQL_RES中读取数据。

typedef struct st_mysql_res {
  my_ulonglong  row_count;
  MYSQL_FIELD   *fields;
  MYSQL_DATA    *data;
  MYSQL_ROWS    *data_cursor;
  unsigned long *lengths;       /* column lengths of current row */
  MYSQL     *handle;        /* for unbuffered reads */
  const struct st_mysql_methods *methods;
  MYSQL_ROW row;            /* If unbuffered read */
  MYSQL_ROW current_row;        /* buffer to current row */
  MEM_ROOT  field_alloc;
  unsigned int  field_count, current_field;
  my_bool   eof;            /* Used by mysql_fetch_row */
  /* mysql_stmt_close() had to cancel this result */
  my_bool       unbuffered_fetch_cancelled;  
  void *extension;
} MYSQL_RES;

3、MYSQL_FIELD中包含了字段名、字段类型和大小等信息。可以重复调用mysql_fetch_field函数获得所有字段的信息。可以通过重复调用mysql_fetch_field()对每一列获得MYSQL_FIELD结构。字段值不是这个结构的部分；它们被包含在一个MYSQL_ROW结构中。

typedef struct st_mysql_field {
  char *name;                 /* Name of column */
  char *org_name;             /* Original column name, if an alias */
  char *table;                /* Table of column if column was a field */
  char *org_table;            /* Org table name, if table was an alias */
  char *db;                   /* Database for table */
  char *catalog;          /* Catalog for table */
  char *def;                  /* Default value (set by mysql_list_fields) */
  unsigned long length;       /* Width of column (create length) */
  unsigned long max_length;   /* Max width for selected set */
  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;         /* Div flags */
  unsigned int decimals;      /* Number of decimals in field */
  unsigned int charsetnr;     /* Character set */
  enum enum_field_types type; /* Type of field. See mysql_com.h for types */
  void *extension;
} MYSQL_FIELD;

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

typedef char **MYSQL_ROW;

1.3、API函数使用步骤

1、首先要包含mysql的头文件，并链接mysql动态库。

#include 

2、创建MYSQL变量。

MYSQL mysql;

3、mysql_init初始化MYSQL变量

4、调用mysql_real_connect函数连接Mysql数据库

5、调用mysql_real_query函数进行数据库查询

6、通过调用mysql_store_result或mysql_use_result函数返回的MYSQL_RES变量获取查询结果数据。

7、调用mysql_fetch_row函数读取结果集数据。

8、结果集用完后，调用mysql_free_result函数释放结果集，以防内存泄露
9、不再查询Mysql数据库时，调用mysql_close函数关闭数据库连接

2、mysql_init()——MYSQL对象初始化

2.1、函数原型及参数说明

分配或初始化与mysql_real_connect()相适应的MYSQL对象

MYSQL *mysql_init(MYSQL *mysql) 

返回值:

• 初始化的MYSQL*句柄。如果无足够内存以分配新的对象，返回NULL。 错误,在内存不足的情况下，返回NULL。

说明：

• 如果mysql是NULL指针，该函数将分配、初始化、并返回新对象。

• 否则，将初始化对象，并返回对象的地址。

• 如果mysql_init()分配了新的对象，应当在程序中调用mysql_close() 来关闭连接，以释放对象

2.2、简单使用

 	MYSQL  mysql;
    if(NULL==mysql_init(&mysql))
      {
         cout << "初始化失败！"<< endl;
         return -1;
      }

3、mysql_real_connect()——数据库引擎建立连接

3.1、函数原型及参数说明

连接数据库引擎，通过函数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*连接句柄。
• 如果连接失败，返回NULL。对于成功的连接，返回值与第1个参数的值相同。

参数说明：

• mysql：前面定义的MYSQL变量；
• host：MYSQL服务器的地址；
  • 如果“host”是NULL或字符串"localhost"，连接将被视为与本地主机的连接。
  • 如果操作系统支持套接字（Unix）或命名管道（Windows），将使用它们而不是TCP/IP连接到服务器。
• user：登录用户名；
  • 如果“user”是NULL或空字符串""，用户将被视为当前用户。在UNIX环境下，它是当前的登录名。
• passwd：登录密码；
• db：要连接的数据库，如果db为NULL，连接会将默认的数据库设为该值。
• port：MYSQL服务器的TCP服务端口；
  • 如果“port”不是0，其值将用作TCP/IP连接的端口号。注意，“host”参数决定了连接的类型。
• unix_socket：unix连接方式。
  • 如果unix_socket不是NULL，该字符串描述了应使用的套接字或命名管道。注意，“host”参数决定了连接的类型。
• clientflag：Mysql运行为ODBC数据库的标记，一般取0。

3.2、简单使用

if(NULL==mysql_real_connect(&mysql,"localhost","root","123456","s",0,NULL,0))
    {
         cout << "初始化失败！"<< endl;
         return -1;
    }

4、mysql_query()——查询数据库某表内容

4.1、函数原型及参数说明

查询数据库中的某一个表内容，通过函数mysql_query()来实现。

int mysql_query(MYSQL *mysql, const char *query) 
//query为执行的SQL语句对应的字符长串

返回值

• 如果查询成功，返回0。如果出现错误，返回非0值。

使用说明：

• 执行由“Null终结的字符串”查询指向的SQL查询。
• 正常情况下，字符串必须包含1条SQL语句，而且不应为语句添加终结分号（‘;’）或“\g”。如果允许多语句执行，字符串可包含多条由分号隔开的语句。（“多查询执行的C API处理”）
• mysql_query()不能用于包含二进制数据的查询，应使用mysql_real_query()取而代之（二进制数据可能包含字符‘\0’，mysql_query()会将该字符解释为查询字符串结束）。
• 如果希望了解查询是否应返回结果集，可使用mysql_field_count()进行检查。

int   mysql_real_query(MYSQL *mysql, const char *q, unsigned long length);

查询成功则该函数返回0。

参数说明：

• mysql：前面定义的MYSQL变量；
• q：SQL查询语句；
• length：查询语句的长度。

4.2、简单使用

int ret=mysql_query(&mysql,sql);
if(ret!=0)
  {
      cout << "sql语句不合法！" << mysql_error(&mysql)) << endl;
      return -1;
  }

5、mysql_store_result()——向客户端检索完整的结果集

函数原型及参数说明

显示查询数据库中数据表的内容，mysql_store_result()将mysql_query()查询的全部结果读取到客户端，分配1个MYSQL_RES结构（上面有介绍），并将结果置于该结构中

MYSQL_RES *mysql_store_result(MYSQL *mysql) 

返回值

具有多个结果的MYSQL_RES结果集合。如果出现错误，返回NULL。

使用说明：

• 对于成功检索了数据的每个查询（SELECT、SHOW、DESCRIBE、EXPLAIN、CHECK TABLE等），必须调用mysql_store_result()或mysql_use_result() 。
• 如果希望了解查询是否应返回结果集，可使用mysql_field_count()进行检查。
• 如果查询未返回结果集，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()。

5.1、mysql_fetch_row()——从结果集中获取下一行

MYSQL_ROW mysql_fetch_row(MYSQL_RES* result)
//MYSQL_ROW开篇已经说明，char ** 类型

返回值

• 下一行的MYSQL_ROW结构。如果没有更多要检索的行或出现了错误，返回NULL。

使用说明：

• 在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]，访问这些值的指针。
• 可以通过调用mysql_fetch_lengths()来获得行中字段值的长度。对于空字段以及包含NULL的字段，长度为0。通过检查字段值的指针，能够区分它们。如果指针为NULL，字段为NULL，否则字段为空。

5.2、mysql_field_count()——返回表的列数

返回作用在连接上的最近查询的列数。

unsigned int mysql_field_count(MYSQL *mysql) 

返回值

• 表示结果集中列数的无符号整数。

使用说明：
该函数的正常使用是在mysql_store_result()返回NULL（因而没有结果集指针）时。在这种情况下，可调用mysql_field_count()来判定mysql_store_result()是否应生成非空结果。这样，客户端就能采取恰当的动作，而无需知道查询是否是SELECT（或类似SELECT的）语句。

5.3、mysql_fetch_fields()——来获取表头的内容

对于结果集，返回所有MYSQL_FIELD结构的数组。每个结构提供了结果集中1列的字段定义。

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result) 
//MYSQL_FIELD 开篇已经说明

返回值

• 关于结果集所有列的MYSQL_FIELD结构的数组。

示例：

result = mysql_store_result(&mysql);
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);
}

5.4、简单使用

		MYSQL_RES *result=NULL;
        MYSQL_ROW  row = NULL;
        int num_rows,num_fields;
        result = mysql_store_result(&mysql);
        num_rows=mysql_num_rows(result);
        num_fields=mysql_num_fields(result);
        printf("行数：%d,列数:%d\n",num_rows,num_fields);  

        for(int i=0;i<num_rows;i++)
        {
                row=mysql_fetch_row(result);//从结果集中获取下一行
                for(int j=0;j<num_fields;j++)
                {
                        printf("%s\t",row[j]);
                }
                printf("\n");
        }		

6、mysql_use_result()——启动逐行结果集检索

6.1、函数原型及参数说明

调用mysql_use_result初始化检索，以便于后面一行一行的读取结果集，而它本身并没有从服务器读取任何数据，这种方式较之第一种速度更快且所需内存更少，但它会绑定服务器，阻止其他线程更新任何表，而且必须重复执行mysql_fetch_row读取数据，直至返回NULL，否则未读取的行会在下一次查询时作为结果的一部分返回，故经常我们使用mysql_store_result。

MYSQL_RES *  mysql_use_result(MYSQL *mysql);

7、mysql_free_result()——释放结果集使用的内存

7.1、函数原型及参数说明

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

void mysql_free_result(MYSQL_RES *result) 

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

8、mysql_close()——关闭数据库连接

8.1、函数原型及参数说明

关闭前面打开的连接。如果句柄是由mysql_init()或mysql_connect()自动分配的，mysql_close()还将解除分配由mysql指向的连接句柄。

void mysql_close(MYSQL *mysql) 

9、应用实例

#include 
#include 
#include 
#include 

int main()
{
    int ret = 0;
    MYSQL mysql;
    MYSQL * connect = NULL;
    connect = mysql_init(&mysql);
    if(connect == NULL){
        ret = mysql_errno(&mysql);
        printf("mysql_init error, %s\n", mysql_error(&mysql));
        return ret;
    }
    printf("mysql_init ok...\n");

    connect = mysql_real_connect(connect, "localhost", "root", "yxk", "test", 0, NULL, 0);
    if(connect == NULL){
        ret = mysql_errno(&mysql);
        printf("mysql_real_connect error, err is: %s\n", mysql_error(&mysql));
        return ret;
    }
    printf("mysql_real_connect ok...\n");
   const char * query = "select * from department";
    ret = mysql_query(connect, query);
    if(ret != 0){
        printf("mysql_query error\n");
        return ret;
    }
    MYSQL_RES *result = mysql_store_result(&mysql);
    if(result == NULL){
        printf("mysql_store_result error\n");
        return -1;
    }

    int field_num = mysql_field_count(&mysql);
    //表头
    MYSQL_FIELD * fields = mysql_fetch_fields(result);
    int i = 0;
    printf("------------------------------------------\n");
    for(i= 0; i < field_num; i++){
        printf("%s \t", fields[i].name); 
    }
    printf("\n------------------------------------------\n");

    //表内容
    MYSQL_ROW row = NULL;
    while(row = mysql_fetch_row(result)){
        for(i= 0; i < field_num; i++){
            printf("%s \t", row[i]); 
        }
        printf("\n");
    }

    mysql_free_result(result);//释放内存
    mysql_close(connect);
    printf("mysql_close...\n");
    return 0;
}

编译：

gcc mysql_test.c -o mysql_test -lmysqlclient

参考

1、https://blog.csdn.net/zxng_work/article/details/78926413
2、https://www.cnblogs.com/Corphish/p/7144162.html
3、https://blog.csdn.net/da_guo_li/article/details/80280289
4、https://blog.csdn.net/Linux_ever/article/details/50651513