Mysql C API部分函数讲解

1、MYSQL *mysql_init(MYSQL *mysql) 分配或初始化与mysql_real_connect()相适应的MYSQL对象。如果mysql是NULL指针，该函数将分配、初始化、并返回新对象。否则，将初始化对象，并返回对象的地址。 
    如果mysql_init()分配了新的对象，当调用mysql_close()来关闭连接时。将释放该对象。初始化的MYSQL*句柄。如果无足够内存以分配新的对象，返回NULL。在内存不足的情况下，返回NULL。 
例：MYSQL mysql; 
mysql_init(&mysql);
或 
MYSQL *mysql = mysql_init(NULL);         
一般定义 MYSQL *mysql,避免取地址操作出错。 
2、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 *：mysql_init函数返回的指针 。
Host：主机地址 本地为localhost，远端为对应服务器的IP地址例如：192.167.1.90。
user/passwd/db：用户名、密码、数据库名。
Port： 数据库端口 。
unix_socket：使用unix连接方式 unix_socket一般为NULL,表明不使用socket或管道机制。       
client_flag：参数经常设置为0 。
注：host为null或localhost时链接的是本地的计算机 。
当mysql默认安装在系统中，root账户是没有密码的，因此用户名使用root，密码为NULL。
当db为空的时候，函数链接到默认数据库，在进行mysql安装时会存在默认的test数据库，因此此处可以使用test数据库名称，port端口为3306 。
返回值:当连接成功时，返回MYSQL连接句柄。失败，返回NULL。当成功时，返回值与第一个参数值是相同的。       
例：MYSQL mysql; 
mysql_real_connect(&mysql,"192.168.1.6","root","","Cacti_Data",atoi("3306"),NULL,0) 
         MYSQL *mysql;
         mysql_real_connect(mysql,"localhost","root",NULL,"test",3306,NULL,0);      
3、int mysql_options(MYSQL *mysql, enum mysql_option option, const char *arg) 
可用于设置额外的连接选项，并影响连接的行为。可多次调用该函数来设置数个选项。应在mysql_init()之后、以及mysql_connect()或mysql_real_connect()之前调用mysql_options()。 
      选项参量指的是你打算设置的选项。arg参量是选项的值。如果选项是整数，那么arg应指向整数的值。
注意，如果使用了MYSQL_READ_DEFAULT_FILE或MYSQL_READ_DEFAULT_GROUP，总会读取客户端组。选项文件中指定的组可能包含下述选项：
 

选项	描述
connect-timeout	以秒为单位连接超时，该超时也用作等待服务器首次回应时间
compress	使用压缩客户端/服务器协议。
database	如果在连接命令中未指定数据库，连接到该数据库。
debug	调试选项。
disable-local-infile	禁止使用LOAD DATA LOCAL。
host	默认主机名。
init-command	连接到MySQL服务器时将执行的命令。
interactive-timeout	等同于将CLIENT_INTERACTIVE指定为mysql_real_connect()。
local-infile[=(0|1)]	如果无参量或参量!= 0，那么将允许使用LOAD DATA LOCAL。
max_allowed_packet	客户端能够从服务器读取的最大信息包。
multi-results	允许多语句执行或存储程序的多个结果集。
multi-statements	允许客户端在1个字符串内发送多条语句。（由“;”隔开）。
password	默认密码。
pipe	使用命名管道连接到NT平台上的MySQL服务器。
protocol={TCP | SOCKET | PIPE | MEMORY}	连接到服务器时将使用的协议。
port	默认端口号。
return-found-rows	通知mysql_info()返回发现的行，而不是使用UPDATE时更新的行。
shared-memory-base-name=name	共享内存名称，用于连接到服务器（默认为"MYSQL"）。
socket	默认的套接字文件。
user	默认用户。

注意，“timeout”（超时）已被“connect-timeout”（连接超时）取代，但为了保持向后兼容，在MySQL 5.1.2-alpha中仍支持“timeout”（超时）。
该函数成功时返回0。如果使用了未知选项，返回非0值。
例：MYSQL mysql;
mysql_init(&mysql);
mysql_options(&mysql,MYSQL_OPT_COMPRESS,0);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"odbc");
if (!mysql_real_connect(&mysql,"host","user","passwd","database",3306,NULL,0))
{
fprintf(stderr, "Failed to connect to database:Error: %s\n",mysql_error(&mysql));

}
 
4、int mysql_query(MYSQL *mysql, const char *query) 
     int mysql_real_query(MYSQL *mysql, const char *query, unsigned long length) 
执行一条由“query”指向的SQL查询。正常情况下，字符串必须包含1条SQL语句，而且不应为语句添加终结分号";"或“\\g”。 如果允许多语句执行，字符串可包含由分号隔开的多条语句。 如果希望知道查询是否应返回结果集，可使用mysql_field_count()进行检查。
如果查询成功，返回0。如果出现错误，返回非0值。
Mysql_query()仅对SELECT、SHOW、EXPLAIN或DESCRIBE语句执行成功返回一个资源标识符，如果查询执行不正确则返回false。对于其它类型的SQL语句，mysql_query()在执行成功时返回0，出错时返回其它值。
错误代码： CR_COMMANDS_OUT_OF_SYNC       以不恰当的顺序执行了命令。CR_SERVER_GONE_ERROR MySQL    服务器不可用。 
 CR_SERVER_LOST   在查询过程中，与服务器的连接丢失。
CR_UNKNOWN_ERROR  出现未知错误。 
注：对于包含二进制数据的查询，必须使用mysql_real_query()，因为二进制数据可能会包含„\\0‟字符。 此外，mysql_real_query()比mysql_query()快，因为它不会在查询字符串上调用strlen()。
例：string tmp = "set names \'gbk\'";
 mysql_real_query(mysql,tmp.c_str(),tmp.length()); 
 
          string sln("tom"); string sql = "select ID,PID,VID from Table1 where Name = \'" + sln + "\'"; 
          mysql_query(mysql, sql.c_str());
5、MYSQL_RES *mysql_store_result(MYSQL *mysql)         返回查询结果集,0没有结果集，非0具有多个结果的MYSQL_RES结果集合。如果出现错误，返回NULL。 
 
MYSQL_RES *mysql_use_result(MYSQL *mysql)    启动查询返回MYSQL_RES结构。     
 
int mysql_num_rows (MYSQL_RES *res)  返回结果集的行数 。
 
unsigned int mysql_field_count(MYSQL *mysql)     返回结果集中行的列数     
unsigned int mysql_num_fields(MYSQL_RES *res) 同上。
 
MYSQL_ROW mysql_fetch_row(MYSQL_RES *res) 从结果集中取得下一行，返回下一行的MYSQL_ROW结构。如果没有更多的行可检索或如果出现一个错误，NULL。 
 
unsigned long *mysql_fetch_lengths(MYSQL_RES *res) 返回在结果集合内的当前行的列长度 。
 
MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *res)  返回行光标当前的偏移量。
 
MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *res, MYSQL_ROW_OFFSET offset) 设置行光标.返回行光标先前的值 。
 
void mysql_free_result(MYSQL_RES *res)释放为一个结果集合分配的内存 。
 
可以调用mysql_fetch_row()来获取结果集中的行，或调用mysql_row_seek()和mysql_row_tell()来获取或设置结果集中的当前行位置。 一旦完成了对结果集的操作，必须调用mysql_free_result()来释放内存。如果成功，mysql_store_result()将复位mysql_error()和mysql_errno()。 
 
注：mysql_store_result() 立即从服务器上检索结果集，并为之分配内存，存储到客户机中而mysql_use_result()只是启动查询,通过mysql_fetch_row()调用即取得一行数据,每个结果的列储存在一个数组的单元中，偏移量从0开始,依次调用取得下一行。 
例： MYSQL_RES *res = mysql_store_result(&mysql);
 MYSQL_ROW *row = mysql_fetch_row(res); 
mysql_free_result(res); 
         unsigned long *lengths; 
lengths = mysql_fetch_lengths(res);
 
void mysql_close(MYSQL *mysql) 关闭一个以前打开了的连接,释放被mysql指向的连接句柄。
 
string mysql_error(MYSQL *mysql); 返回最近一次MySQL函数的执行状态。     
 
unsigned int mysql_errno(MYSQL *mysql)返回最近调用的API函数的错误代码 。
例:string err_str = mysql_error(mysql); 常用于数据库断开重连,下例执行SQl语句过程中出错重连。 
if(err_str == "Lost connection to MySQL server during query" || err_str == "Malformed packet") 
           {mysql_close(mysql); mysql = NULL; return Reconnect(...);}
 
以下代码块是用来连接数据库的通讯过程，要连接MYSQL，必须建立MYSQL实例，通过mysql_init初始化方能开始进行连接。
typedefstruct st_mysql {
  NET          net;            /* Communicationparameters */
  gptr         connector_fd;   /* ConnectorFd forSSL */
  char         *host,*user,*passwd,*unix_socket,
               *server_version,*host_info,*info,*db;
  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 inmysql_close */
  my_bool      reconnect;      /* set to 1 ifautomatic reconnect */
  struct st_mysql_options options;
  char         scramble_buff[9];
  struct charset_info_st *charset;
  unsigned int server_language;
} MYSQL;
 
这个结构代表返回行的一个查询的(SELECT, SHOW, DESCRIBE, EXPLAIN)的结果。返回的数据称为“数据集”，用过数据库的朋友应该对数据库中查询后得到的结果集不会陌生，在C的API里对应的就是MYSQL_RES了，从数据库读取数据，最后就是从MYSQL_RES中读取数据。
typedefstruct 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;            /* If unbufferedread */
  MYSQL_ROW    current_row;    /* buffer tocurrent row */
  unsigned long     *lengths;       /* columnlengths of current row */
  MYSQL        *handle;        /* for unbufferedreads */
  my_bool      eof;            /* Used my mysql_fetch_row */
}MYSQL_RES;