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 int client_flag)
Описание
Функция mysql_real_connect() пытается установить соединение с сервером баз
данных MySQL, работающим на хосте host. До успешного завершения функции
mysql_real_connect() нельзя выполнять никакие другие функции интерфейса, за
исключением mysql_get_client_info().
Параметры этой функции указываются следующим образом:
Первым параметром должен быть указатель существующей структуры
MYSQL. До вызова функцииmysql_real_connect() необходимо вызвать функциюmysql_init()для инициализации данной структурыMYSQL. Вызов функцииmysql_options()позволяет изменить многие опции данного соединения. See Раздел 8.4.3.39, «mysql_options()».hostможет быть как именем хоста, так и IP-адресом. Если host равенNULLили строке"localhost", то подразумевается соединение с локальным хостом. Если операционная система поддерживает сокеты (Unix) или именованные каналы (Windows), то они используются вместо протокола TCP/IP для соединения с сервером.Параметр user содержит имя данного пользователя MySQL. Если параметр user равен
NULL, то подразумевается текущий пользователь. Под операционной системой Unix, это будет текущее имя входа в систему. Под Windows ODBC имя пользователя должно быть указано явным образом. См. раздел See Раздел 8.3.2, «Как заполнять различные поля в Администраторе ODBC».-
Параметр
passwdсодержит пароль для user. Если параметрpasswdравенNULL, то только записи в таблицеuserдля пользователя, имеющего чистое (пустое) поле пароля, будут проверяться на совпадение. Это дает возможность администратору базы данных устанавливать систему прав MySQL таким образом, что пользователи получают различные права, в зависимости от того, имеют они или нет установленный пароль.Замечание: не следует пытаться шифровать пароль перед вызовом функции
mysql_real_connect(); шифрование пароля производится автоматически библиотекой. Параметр
dbпредставляет собой имя базы данных. Если параметрdbне равенNULL, то данное соединение установит эту величину в качестве базы данных по умолчанию.Если параметр
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секунд) перед закрытием данного соединения.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Не удалось создать именованный канал на 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 будет читать секции
[client] и [your_prog_name] в конфигурационном файле my.cnf, что будет
гарантировать нормальную работу данной программы, даже если MySQL будет
установлен нестандартным образом.
Следует заметить, что во время соединения функция mysql_real_connect()
устанавливает флаг reconnect (часть данной структуры MYSQL) в значение,
равное 1. Этот флаг показывает, что в случае, если запрос не может быть
выполнен из-за потери соединения, то следует попытаться восстановить
соединение прежде, чем отказаться от него.
