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_real_connect()尝试与运行在主机上的MySQL数据库引擎建立连接。在你能够执行需要有效MySQL连接句柄结构的任何其他API函数之前,mysql_real_connect()必须成功完成。

参数的指定方式如下:

·         1个参数应是已有MYSQL结构的地址。调用mysql_real_connect()之前,必须调用mysql_init()来初始化MYSQL结构。通过mysql_options()调用,可更改多种连接选项。请参见25.2.3.48节,“mysql_options()”

·         host”的值必须是主机名或IP地址。如果“host”是NULL或字符串"localhost",连接将被视为与本地主机的连接。如果操作系统支持套接字(Unix)或命名管道(Windows),将使用它们而不是TCP/IP连接到服务器。

·         user”参数包含用户的MySQL登录ID。如果“user”NULL或空字符串"",用户将被视为当前用户。在UNIX环境下,它是当前的登录名。在Windows ODBC下,必须明确指定当前用户名。请参见26.1.9.2节,“在Windows上配置MyODBC DSN”

·         passwd”参数包含用户的密码。如果“passwd”NULL仅会对该用户的(拥有1个空密码字段的)用户表中的条目进行匹配检查。这样,数据库管理员就能按特定的方式设置MySQL权限系统,根据用户是否拥有指定的密码,用户将获得不同的权限。

注释:调用mysql_real_connect()之前,不要尝试加密密码,密码加密将由客户端API自动处理。

·         “db”是数据库名称。如果dbNULL连接会将默认的数据库设为该值。

·         如果“port”不是0其值将用作TCP/IP连接的端口号。注意,“host”参数决定了连接的类型。

·         如果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_real_connect()调用中的确切值。为此,在调用mysql_real_connect()之前,应与MYSQL_READ_DEFAULT_FILEMYSQL_READ_DEFAULT_GROUP选项一起调用mysql_options()。随后,在mysql_real_connect()调用中,为准备从选项文件读取值的每个参数指定“无值”值:

·         对于host,指定NULL值或空字符串("")

·         对于user,指定NULL值或空字符串。

·         对于passwd,指定NULL值。(对于密码,mysql_real_connect()调用中的空字符串的值不能被选项文件中的字符串覆盖,这是因为,空字符串明确指明MySQL账户必须有空密码)。

·         对于db,指定NULL值或空字符串

·         对于port,指定“0”值。

·         对于unix_socket指定NULL值。

对于某一参数,如果在选项文件中未发现值,将使用它的默认值,如本节前面介绍的那样。

返回值

如果连接成功,返回MYSQL*连接句柄。如果连接失败,返回NULL。对于成功的连接,返回值与第1个参数的值相同。

错误

·         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

无法在Windows平台下创建命名管道。

·         CR_NAMEDPIPEWAIT_ERROR

Windows平台下等待命名管道失败。

·         CR_NAMEDPIPESETSTATE_ERROR

Windows平台下获取管道处理程序失败。

·         CR_SERVER_LOST

如果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));
}

通过使用mysql_options()MySQL库将读取my.cnf文件的[client][your_prog_name]部分,以确保程序工作,即使某人以某种非标准的方式设置MySQL也同样。

注意,一旦建立了连接,mysql_real_connect()将设置再连接标志(MYSQL结构的组成部份)的值,在低于5.0.3版的API中,将其设为“1”,在较新的版本中,将其设为“0”。对于该标志,值“1”表示,如果因连接丢失而无法执行语句,放弃前,将尝试再次连接到服务器。从MySQL 5.0.13开始,可以对mysql_options()使用MYSQL_OPT_RECONNECT选项,对再连接行为进行控制。