mysql-C-API常用函数

关于返回值：

返回值的函数通常会返回指针或整数。除非作了其他规定，返回指针的函数将返回非Null值，以指明成功，或返回NULL值以指明出错。返回整数的函数将返回0以指明成功，或返回非0值以指明出错。注意，非0值仅表明这点。除非在函数描述中作了其他说明，不要对非0值进行测试：

if (result)                   /* correct */ 正确做法

    ... error ... 

if (result < 0)               /* incorrect */ 不要进行测试

    ... error ... 

if (result == -1)             /* incorrect */ 同上

    ... error ...

通过调用mysql_errno()可发现出现的错误原因或者通过mysql_error(),获得错误标志

函数：

1：MYSQL *mysql_init(MYSQL *mysql) 

描述：分配或初始化与mysql_real_connect()相适应的MYSQL对象。如果mysql是NULL指针，该函数将分配、初始化、并返回新对象。否则，将初始化对象，并返回对象的地址。如果mysql_init()分配了新的对象，当调用mysql_close()来关闭连接时。将释放该对象。
返回值：初始化的MYSQL*句柄。如果无足够内存以分配新的对象，返回NULL。 
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) 
参数：
·         第1个参数应是已有MYSQL结构的地址。调用mysql_real_connect()之前，必须调用mysql_init()来初始化MYSQL结构。通过mysql_options()调用，可更改多种连接选项。
·         “host”的值必须是主机名或IP地址。如果“host”是NULL或字符串"localhost"，连接将被视为与本地主机的连接。
·         “user”参数包含用户的MySQL登录ID。如果“user”是NULL或空字符串""，用户将被视为当前用户。
·         “passwd”参数包含用户的密码。
注释：调用mysql_real_connect()之前，不要尝试加密密码，密码加密将由客户端API自动处理。
·         “db”是数据库名称。如果db为NULL，连接会将默认的数据库设为该值。
·         如果“port”不是0，其值将用作TCP/IP连接的端口号。注意，“host”参数决定了连接的类型。一般指定“0”值。
·         如果unix_socket不是NULL，该字符串描述了应使用的套接字或命名管道。注意，“host”参数决定了连接的类型。
·         client_flag的值通常为0，但是，也能将其设置为下述标志的组合，以允许特定功能：
CLIENT_COMPRESS
使用压缩协议。
CLIENT_FOUND_ROWS
返回发现的行数（匹配的），而不是受影响的行数。
CLIENT_IGNORE_SPACE
允许在函数名后使用空格。使所有的函数名成为保留字。
CLIENT_INTERACTIVE
关闭连接之前，允许interactive_timeout（取代了wait_timeout）秒的不活动时间。客户端的会话wait_timeout变量被设为会话interactive_timeout变量的值。
CLIENT_LOCAL_FILES
允许LOAD DATA LOCAL处理功能。
CLIENT_MULTI_STATEMENTS
通知服务器，客户端可能在单个字符串内发送多条语句（由‘;’隔开）。如果未设置该标志，将禁止多语句执行。
CLIENT_MULTI_RESULTS
通知服务器，客户端能够处理来自多语句执行或存储程序的多个结果集。如果设置了CLIENT_MULTI_STATEMENTS，将自动设置它。
CLIENT_NO_SCHEMA
禁止db_name.tbl_name.col_name语法。它用于ODBC。如果使用了该语法，它会使分析程序生成错误，在捕获某些ODBC程序中的缺陷时，它很有用。
CLIENT_ODBC
客户端是ODBC客户端。它将mysqld变得更为ODBC友好。
CLIENT_SSL
使用SSL（加密协议）。该选项不应由应用程序设置，它是在客户端库内部设置的。
 
返回值：如果连接成功，返回MYSQL*连接句柄。如果连接失败，返回NULL。
错 误：
·         CR_CONN_HOST_ERROR 无法连接到MySQL服务器。
·         CR_CONNECTION_ERROR 无法连接到本地MySQL服务器。
·         CR_IPSOCK_ERROR 无法创建IP套接字。
·         CR_OUT_OF_MEMORY 内存溢出。 
·         CR_SOCKET_CREATE_ERROR 无法创建Unix套接字。
·         CR_UNKNOWN_HOST 无法找到主机名的IP地址。
·         CR_VERSION_ERROR 协议不匹配，起因于：试图连接到具有特定客户端库（该客户端库使用了不同的协议版本）的服务器。如果使用很早的客户端库来建立与较新的服务器（未使用“--old-protocol”选项开始的）的连接，就会出现该情况。
·         CR_NAMEDPIPEOPEN_ERROR 如果connect_timeout > 0，而且在连接服务器时所用时间长于connect_timeout秒，或在执行init-command时服务器消失。
示例：
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));
}
3：unsigned long mysql_real_escape_string(MYSQL *mysql, char *to, const char *from, unsigned long length) 
描述：按照连接的当前字符集，将“from”中的字符串编码为转义SQL字符串。将结果置于“to”中，并添加1个终结用NULL字节，“from”指向的字符串必须是长度字节“long”。必须为“to”缓冲区分配至少length*2+1字节。“to”的内容是由Null终结的字符串。
返回值：返回值是编码字符串的长度，不包括终结用Null字符。
示例：
char query[1000],*end;
 
end = strmov(query,"INSERT INTO test_table values(");
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,"What's this",11);
*end++ = '\'';   *end++ = ',';   *end++ = '\'';
end += mysql_real_escape_string(&mysql, end,"binary data: \0\r\n",16);
*end++ = '\'';   *end++ = ')';
 
if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))
{
   fprintf(stderr, "Failed to insert row, Error: %s\n",
           mysql_error(&mysql));
}
该示例中使用的strmov()函数包含在mysqlclient库中，工作方式与strcpy()类似，但会返回指向第1个参数终结用Null的指针。
4：int mysql_real_query(MYSQL *mysql, const char *query, unsigned long length) 
描述：执行由“query”指向的SQL查询，它应是字符串长度字节“long”。正常情况下，字符串必须包含1条SQL语句，而且不应为语句添加终结分号（‘;’）或“\g”。如果允许多语句执行，字符串可包含由分号隔开的多条语句。
返回值：查询成功，返回0。如果出现错误，返回非0值。 
错误：
·         CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令。 
·         CR_SERVER_GONE_ERROR    MySQL服务器不可用。 
·         CR_SERVER_LOST 在查询过程中，与服务器的连接丢失。 
·         CR_UNKNOWN_ERROR 出现未知错误。  
5：MYSQL_RES *mysql_store_result(MYSQL *mysql) 
描述：对于成功检索了数据的每个查询（SELECT、SHOW、DESCRIBE、EXPLAIN、CHECK TABLE等），必须调用mysql_store_result()或mysql_use_result() 。
如果结果不等于NULL可调用mysql_num_rows()来找出结果集中的行数。可以调用mysql_fetch_row()来获取结果集中的行，或调用mysql_row_seek()和mysql_row_tell()来获取或设置结果集中的当前行位置。必须调用mysql_free_result()。
返回值：具有多个结果的MYSQL_RES结果集合。如果出现错误，返回NULL
错误：
如果成功，mysql_store_result()将复位mysql_error()和mysql_errno()。
·         CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令。 
·         CR_OUT_OF_MEMORY 内存溢出。 
·         CR_SERVER_GONE_ERROR MySQL服务器不可用。 
·         CR_SERVER_LOST 在查询过程中，与服务器的连接丢失。 
·         CR_UNKNOWN_ERROR 出现未知错误。  
6：my_ulonglong mysql_num_rows(MYSQL_RES *result)
描述：返回结果集中的行数。
返回值：如果使用了mysql_store_result()，可以立刻调用mysql_num_rows()。如果使用了mysql_use_result()，mysql_num_rows()不返回正确的值，
 7：my_ulonglong mysql_affected_rows(MYSQL *mysql) 
描述：返回上一次作用行数：可在mysql_query()后立刻调用。对于SELECT语句，mysql_affected_rows()的工作方式与mysql_num_rows()类似。如果新行替代了旧行，mysql_affected_rows()返回2。
返回值：大于0的整数表明受影响或检索的行数。“0”表示UPDATE语句未更新记录，-1表示返回错误：由于mysql_affected_rows()返回无符号值，通过比较返回值和“(my_ulonglong)-1”或等效的“(my_ulonglong)~0”，检查是否为“-1”。
示例：
mysql_query(&mysql,"UPDATE products SET cost=cost*1.25 WHERE group=10");
printf("%ld products updated",(long) mysql_affected_rows(&mysql)); 
8：MYSQL_ROW mysql_fetch_row(MYSQL_RES *result) 
描述：返回结果集的下一行，没有时为NULL。
错误：
·         CR_SERVER_LOST 在查询过程中，与服务器的连接丢失。
示例：
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");
} 
9：unsigned int mysql_num_fields(MYSQL_RES *result)
描述：返回每行的字段数
10：unsigned long *mysql_fetch_lengths(MYSQL_RES *result) 
描述：返回各个字段中数据的真实长度
示例：
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]);
    }
}
11：unsigned int mysql_field_count(MYSQL *mysql) 
描述：返回作用在连接上的最近查询的列数
示例：
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));
        }
    }
}
12：int mysql_options(MYSQL *mysql, enum mysql_option option, const char *arg) 
描述：可用于设置额外的连接选项，并影响连接的行为。可多次调用该函数来设置数个选项。
应在mysql_init()之后、以及mysql_connect()或mysql_real_connect()之前调用mysql_options()。
可能的选项值：http://dev.mysql.com/doc/refman/5.1/zh/apis.html#mysql-options
返回值：成功时返回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",0,NULL,0))
{
    fprintf(stderr, "Failed to connect to database: Error: %s\n",
          mysql_error(&mysql));
}
该代码请求客户端使用压缩客户端／服务器协议，并从my.cnf文件的obdc部分读取额外选项。
13：int mysql_ping(MYSQL *mysql) 
描述：检查与服务器的连接是否工作，连接丢失，将自动尝试再连接。该函数可被闲置了较长时间的客户端使用，用以检查服务器是否已关闭了连接，并在必要时再次连接。
返回值：如果与服务器的连接有效返回0。如果出现错误，返回非0值。返回的非0值不表示MySQL服务器本身是否已关闭，连接可能因其他原因终端，如网络问题等。
错误：
·         CR_COMMANDS_OUT_OF_SYNC  以不恰当的顺序执行了命令。 
·         CR_SERVER_GONE_ERROR   MySQL服务器不可用。 
·         CR_UNKNOWN_ERROR   出现未知错误。 
14：MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result) 
描述：对于结果集，返回所有MYSQL_FIELD结构的数组。每个结构提供了结果集中1列的字段定义。
示例：
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);
}
 
15：void mysql_close(MYSQL *mysql) 
描述：关闭前面打开的连接。如果句柄是由mysql_init()或mysql_connect()自动分配的，mysql_close()还将解除分配由mysql指向的连接句柄。