О плагине MySQL R40 от pBlueG (описание нововведений/отличия от R39 и т.п.)
Доброго времени суток.
Не так давно вышла новая версия плагина MySQL - R40.
В данной статье я постараюсь рассказать Вам о том, каким изменениям подвергся плагин в сравнении с версией R39.
Начнём.
Ссылки на сторонние ресурсы:
- GitHub - тут Вы можете скачать актуальную версию/посмотреть лог разработки/сообщить о багах и т.п.
- SA-MP wiki - тут Вы можете увидеть описание всех функций плагина
Что нового:
- Изменения, коснувшиеся функций:
Открыть/закрыть - Удалён параметр "connectionHandle" из всех функций, работающих с кэшем
Подробнее В R39 был ряд функций, которые работали с кэшем. Вот их список:
Открыть/закрыть
PHP код:
// Cache functions
native cache_get_data(&num_rows, &num_fields, connectionHandle = 1);
native cache_get_row_count(connectionHandle = 1);
native cache_get_field_count(connectionHandle = 1);
native cache_get_field_name(field_index, destination[], connectionHandle = 1, max_len = sizeof(destination));
native cache_get_row(row, field_idx, destination[], connectionHandle = 1, max_len = sizeof(destination));
native cache_get_row_int(row, field_idx, connectionHandle = 1);
native Float:cache_get_row_float(row, field_idx, connectionHandle = 1);
native cache_get_field_content(row, const field_name[], destination[], connectionHandle = 1, max_len = sizeof(destination));
native cache_get_field_content_int(row, const field_name[], connectionHandle = 1);
native Float:cache_get_field_content_float(row, const field_name[], connectionHandle = 1);
native Cache:cache_save(connectionHandle = 1);
native cache_delete(Cache:cache_id, connectionHandle = 1);
native cache_set_active(Cache:cache_id, connectionHandle = 1);
native cache_is_valid(Cache:cache_id, connectionHandle = 1);
native cache_affected_rows(connectionHandle = 1);
native cache_insert_id(connectionHandle = 1);
native cache_warning_count(connectionHandle = 1);
native cache_get_query_exec_time(E_EXECTIME_UNIT:unit = UNIT_MICROSECONDS);
native cache_get_query_string(destination[], max_len = sizeof(destination));
Как Вы можете заметить, практически в каждой функции имеется параметр connectionHandle, в который нужно было передавать ID подключения. Именно этот параметр и убрали в новой версии.
- Во все функции, имеющие параметр "connectionHandle", добавлен тег "MySQL" для этого параметра
Подробнее В новой версии переменная, в которую записывалось ID подключения, теперь должна объявляться с использованием тега "MySQL".
Пример:
PHP код:
new MySQL:mysql_connect_ID;
Сделано это, как я понимаю, для того, чтоб исключить ситуации, когда Вы по ошибке указали в качестве переменной с ID какую-либо другую переменную.
Например, перепутали параметры местами (пример для R39):
Вместо
PHP код:
cache_get_field_content(0, "player_name", pInfo[playerid][pName], mysql_connect_ID, MAX_PLAYER_NAME);
написали
PHP код:
cache_get_field_content(0, "player_name", pInfo[playerid][pName], MAX_PLAYER_NAME);
Раньше такой код скомпилировался бы без каких-либо проблем.
Теперь компилятор сообщит об ошибке вот таким предупреждением:
PHP код:
warning 213: tag mismatch
- Из имён членов перечислений (enum) удалены префиксы (было "LOG_ERROR" - стало "ERROR")
Подробнее
Вот список всех перечислений, которые подверглись изменению:
E_LOGLEVEL
Удалён префикс "LOG_"
Как было в R39 enum E_LOGLEVEL
{
LOG_NONE = 0,
LOG_ERROR = 1,
LOG_WARNING = 2,
LOG_DEBUG = 4,
LOG_ALL = LOG_ERROR | LOG_WARNING | LOG_DEBUG
};
Как стало в R40
PHP код:
enum E_LOGLEVEL
{
NONE = 0,
ERROR = 1,
WARNING = 2,
INFO = 4,
DEBUG = 8,
ALL = ERROR | WARNING | INFO | DEBUG
};
E_EXECTIME_UNIT
Удалён префикс "UNIT_"
Как было в R39
PHP код:
enum E_EXECTIME_UNIT
{
UNIT_MILLISECONDS,
UNIT_MICROSECONDS
};
Как стало в R40
PHP код:
enum E_MYSQL_EXECTIME_UNIT
{
MILLISECONDS,
MICROSECONDS
};
- Параметр "MySQL:handle" перемещён на последнюю позицию в следующих функциях: mysql_escape_string, mysql_stat, mysql_get_charset
Подробнее
Как было в R39
PHP код:
mysql_escape_string(const source[], destination[], connectionHandle = 1, max_len = sizeof(destination));
mysql_stat(destination[], connectionHandle = 1, max_len = sizeof(destination));
mysql_get_charset(destination[], connectionHandle = 1, max_len = sizeof(destination));
Как стало в R40
PHP код:
mysql_escape_string(const source[], destination[], max_len = sizeof(destination), MySQL:handle = MYSQL_DEFAULT_HANDLE);
mysql_stat(destination[], max_len = sizeof(destination), MySQL:handle = MYSQL_DEFAULT_HANDLE);
mysql_get_charset(destination[], max_len = sizeof(destination), MySQL:handle = MYSQL_DEFAULT_HANDLE);
- Параметры "password[]" и "database[]"в функции "mysql_connect" поменяны местами
Подробнее
Как было в R39
PHP код:
mysql_connect(const host[], const user[], const database[], const password[], /*...*/);
Как стало в R40
PHP код:
mysql_connect(const host[], const user[], const password[], const database[], /*...*/);
- Дополнительные параметры подключения из "mysql_connect" перенесены в отдельную систему. Добавлены функции для работы с этими параметрами: mysql_init_options и mysql_set_option
Подробнее Под дополнительными параметрами подразумеваются последние параметры mysql_connect из R39: "
port = 3306, bool:autoreconnect = true, pool_size = 2".
В новой версии плагина этих параметров стало больше, что подтолкнуло перенести их в отдельную систему.
Новые функции выглядят так:
PHP код:
native MySQLOpt:mysql_init_options();
native mysql_set_option(MySQLOpt:option_id, E_MYSQL_OPTION:type, ...);
Подробнее о том, какие есть опции и как правильно их изменять, я расскажу ниже.
- Функция "mysql_option" переименована в "mysql_global_options"
- Функция "cache_get_data" (Используйте "cache_get_*_count")
Подробнее
Раньше для того, чтоб узнать, вернул ли запрос какие-либо строки (нашёл ли игрока в таблице и т.п.), многие использовали такую конструкцию:
PHP код:
new rows, fields;
cache_get_data(rows, fields, mysql_connect_ID);
if(!rows) print("Игрок не найден");
else print("Игрок найден");
И получалось, что число столбцов (fields) извлекалось из таблицы понапрасну (хотя и в R39 были такие функции, как "cache_get_row_count/cache_get_field_count").
Вообще очень редко бывают случаи, когда в скрипте нужно узнать одновременно и число строк, и число столбцов. Поэтому эта функция и была удалена. В новой версии конструкция, что предоставлена выше, выглядеть будет так:
PHP код:
new rows;
cache_get_row_count(rows);
if(!rows) print("Игрок не найден");
else print("Игрок найден");
А для того, чтоб узнать число столбцов, есть функция cache_get_field_count, которая записывается точно так же.
- Из функции "orm_delete" удалён параметр "clearvars". Вместо этого появилась отдельная функция "orm_clear_vars"
- Функция "cache_get_row" переименована в "cache_get_value_index" (Аналоги с постфиксом "_int" и "_float", соответственно, тоже)
Подробнее
Как было в R39
PHP код:
native cache_get_row(row, field_idx, destination[], connectionHandle = 1, max_len = sizeof(destination));
native cache_get_row_int(row, field_idx, connectionHandle = 1);
native Float:cache_get_row_float(row, field_idx, connectionHandle = 1);
Как стало в R40
PHP код:
native cache_get_value_index(row_idx, column_idx, destination[], max_len = sizeof(destination));
native cache_get_value_index_int(row_idx, column_idx, &destination);
native cache_get_value_index_float(row_idx, column_idx, &Float:destination);
Обратите внимание на то, что числа теперь возвращаются так же, как и строка - отдельным параметром "destination"
Пример:
PHP код:
//Как было
new buff[30];
cache_get_row(0, 0, buff, mysql_connect_ID, 30);
printf("Первый столбец, возвращённый запросом, имеет значение \"%s\"", buff);
PHP код:
//Как стало
new buff[30];
cache_get_value_index(0, 0, buff, 30); //Напомню, что параметр "connectionHandle" удалён из всех функций, работающих с кэшем
printf("Первый столбец, возвращённый запросом, имеет значение \"%s\"", buff);
- Функция "cache_get_field_content" переименована в "cache_get_value_name" (Аналоги с постфиксом "_int" и "_float", соответственно, тоже)
Подробнее
Как было в R39
PHP код:
native cache_get_field_content(row, const field_name[], destination[], connectionHandle = 1, max_len = sizeof(destination));
native cache_get_field_content_int(row, const field_name[], connectionHandle = 1);
native Float:cache_get_field_content_float(row, const field_name[], connectionHandle = 1);
Как стало в R40
PHP код:
native cache_get_value_name(row_idx, const column_name[], destination[], max_len = sizeof(destination));
native cache_get_value_name_int(row_idx, const column_name[], &destination);
native cache_get_value_name_float(row_idx, const column_name[], &Float:destination);
Обратите внимание на то, что числа теперь возвращаются так же, как и строка - отдельным параметром "destination"
Пример:
PHP код:
//Как было
new player_name[MAX_PLAYER_NAME],
player_level,
Float:player_health;
cache_get_field_content(0, "name", player_name, mysql_connect_ID, MAX_PLAYER_NAME);
player_level = cache_get_field_content_int(0, "level", mysql_connect_ID);
player_health = cache_get_field_content_float(0, "health", mysql_connect_ID);
printf("Имя игрока - \"%s\"", player_name);
printf("Уровень игрока - \"%d\"", player_level);
printf("Здоровье игрока - \"%0.1f\"", player_health);
PHP код:
//Как стало
new player_name[MAX_PLAYER_NAME],
player_level,
Float:player_health;
cache_get_value_name(0, "name", player_name, MAX_PLAYER_NAME);
cache_get_value_name_int(0, "level", player_level);
cache_get_value_name_float(0, "health", player_health);
printf("Имя игрока - \"%s\"", player_name);
printf("Уровень игрока - \"%d\"", player_level);
printf("Здоровье игрока - \"%0.1f\"", player_health);
- Все функции, начинающиеся с "cache_get_*" (в том числе и cache_get_value_index_bool и cache_get_row_count) теперь возвращают значения через отдельный параметр, а не в качестве результата.
Подробнее
Рассмотрим пример с "cache_get_value_name_int"/"cache_get_field_content_int".
В R39 "cache_get_field_content_int" работала следующим образом:
PHP код:
new value;
value = cache_get_field_content_int(0, "value", mysql_connect_ID);
То есть, число, хранящееся в столбце "value", возвращалось в качестве результата работы функции.
В новой версии все функции работы с кэшем приведены к одному стилю: "имя
функции(
порядковый_номер_строки,
имя_столбца,
возвращаемое_значение)".
То есть, теперь число, хранящееся в столбце "value" будет возвращаться в параметре "возвращаемое_значение", а не как результат работы функции. Пример выше будет выглядеть так:
PHP код:
new value;
cache_get_value_name_int(0, "value", value);
То же самое и с остальными функциями.
- Удалён параметр "logtype" из функции "mysql_log". Теперь для логов нельзя установить HTML формат (только текст)
- Добавлена полная совместимость с инклюдом "y_inline"
- Функция "cache_set_active" с указанным в ней "0" больше не делает кэш неактивным. Вместо этого появилась отдельная функция "cache_unset_active()"
Подробнее
Как было в R39
PHP код:
public OnDialogResponse(playerid, dialogid, response, listitem, inputtext[])
{
switch(dialogid)
{
case dLogin:
{
cache_set_active(pInfo[playerid][Data]);
pInfo[playerid][pMoney] = cache_get_field_content_int(0, "money");
pInfo[playerid][pPosX] = cache_get_field_content_float(0, "pos_x");
// ...
cache_set_active(Cache:0); //Делаем кэш неактивным
}
}
return 1;
}
Как стало в R40
PHP код:
public OnDialogResponse(playerid, dialogid, response, listitem, inputtext[])
{
switch(dialogid)
{
case dLogin:
{
cache_set_active(pInfo[playerid][Data]);
cache_get_value_name_int(0, "money", pInfo[playerid][pMoney]);//
cache_get_value_name_float(0, "pos_x", pInfo[playerid][pPosX]);
// ...
cache_unset_active(); //Делаем кэш неактивным
}
}
return 1;
}
- Удалены функции "mysql_reconnect" и "mysql_current_handle"
- Основные изменения в работе плагина:
Открыть/закрыть
- Сохранённый кэш теперь обрабатывается на глобальном уровне, а не для каждого конкретного соединения в отдельности, как было раньше. Это означает, что теперь Вы можете обращаться к кэшу (записывать и извлекать из него что-либо), который был сохранён, например, в моде, в любом из подключённых скриптов (и наоборот: в скриптах из мода/в скриптах из скриптов)
- Удалено автоматическое переподключение (В прошлых версиях плагин хранил в памяти учётные данные о текущем соединении для того, чтоб, в случае возникновения определённых ошибок, выполнить отсоединение от базы данных и повторно подсоединиться к ней. Теперь плагин учётные данные в памяти не хранит)
- Все функции плагина теперь возвращают "1" в случае успешного выполнения функции и "0" в случае возникновения какой-либо ошибки.
- Нововведения:
Открыть/закрыть - Добавлена возможность одновременной работы с несколькими кэшами (раньше при отправке одного SELECT-запроса, начале обработки полученного результата и попытке отправки второго SELECT-запроса, кэш первого запроса автоматически удалялся, если он не был сохранён вручную)
- Добавлена возможность передачи массивов и ссылок в качестве аргументов коллбэка для обработки результата запроса (вид спецификаторов: "a" и "r") (при использовании спецификатора "a", после него следует указать спецификатор "i" или "d", в который следует передать размер передаваемого массива. Так же под этот спецификатор нужно выделить аргумент в самого коллбэка)
- Новая система логирования
- Автоматический поиск дебаг-информации (требуется компиляция с одним из ключей: -d2/-d3): если система логирования обнаружит в скрипте дебаг-информацию, в логах плагина отобразится имя скрипта и номер строки, в которой произошла ошибка (От DeimoS: как в crashdetect)
- Потоковое логирование: новая система логирования теперь полностью мультипоточна и краш-безопасна, что приводит к более быстрой работе (особенно если включены все уровни (mysql_log(ALL))
- Полностью автономна: другие авторы плагинов могут подключить к своему плагину эту систему и воспользоваться быстрой, безопасной и настраиваемой системой логирования.
- Возможность создания SSL-шифрованных подключений
- Функции "orm_update" и "orm_delete" теперь поддерживают возврат результата в коллбэке
- Функция "mysql_query_file": отправляет однопоточный запрос из файла с расширением ".sql"
- Функция "mysql_connect_file": извлекает данные для подключения к базе данных из файла (который имеет все учётные данные и дополнительные опции в удобном INI формате)
- Функция "orm_clear_vars": устанавливает всем переменным, зарегистрированным в указанном ORM, значение "0"
- Функция "cache_is_value_null": вернёт "true" если в указанной ячейке находится значение "NULL"
- Функция "cache_get_value_bool:: Вернёт "false", если значение равно 0, иначе - "true"
- Функция "cache_get_value" расширение: вместо вызова, например, "cache_get_value_index_int(0, 0)" теперь можно использовать вариант без "index/name" части: "cache_get_value_int(0, 0)" (это будет удобно для больших по объёму запросов)
Это относится и к остальным "cache_get_value" функциям (в том числе и "cache_is_value_null")
- Функция "cache_get_field_type": возвращает тип столбца
- Функция "cache_unset_active": устанавливает отсутствие активного кэша
Более подробно о некоторых нововведениях:
- Дополнительные опции при подключении к БД
В MySQL R40 появились 2 новых функции:
Открыть/закрыть - mysql_init_options
Описание:
Создает "хранилище" опций для подключения к базе данных MySQL со значениями по умолчанию.
Параметры
Эта функция не имеет параметров
Возвращаемое значение:
ID созданного "хранилища"
Пример использования:
PHP код:
new MySQLOpt:options = mysql_init_options();
- mysql_set_option
Описание:
Включает/отключает указанную опцию
Параметры
PHP код:
(MySQLOpt:option_id, E_MYSQL_OPTION:type, ...)
option_id - ID "хранилища" опций, возвращенного mysql_init_options
type - Тип опции (таблицу предоставлю ниже)
... - Тут указывается значение для опции
Возвращаемое значение:
"1", если изменение опции прошло успешно. "0" - если произошла какая-либо ошибка
Пример использования:
PHP код:
new MySQLOpt:options = mysql_init_options();
mysql_set_option(options, AUTO_RECONNECT, false); // отключение авто-переподключения к БД
mysql_set_option(options, POOL_SIZE, 0); // отключение многопоточности (соответственно, "mysql_pquery" так же не будет работать)
mysql_set_option(options, SERVER_PORT, 3310); // изменение порта, по которому будет идти подключение
mysql_connect_ID = mysql_connect_ID = mysql_connect(MYSQL_HOST, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE, options);
Таблица опций
Макрос опции |
Тип данных, с которыми работает опция |
Описание опции |
AUTO_RECONNECT |
boolean (true/false)
По умолчанию: true (включено) |
Совершать ли плагину попытки переподключиться к серверу при потере соединения или нет |
MULTI_STATEMENTS |
boolean (true/false)
По умолчанию: false (запрещено) |
Разрешить/запретить отправку нескольких SQL-запросов в одном.
То бишь, возможность одним запросом отправить, например, две команды "INSERT INTO" или же "SELECT + INSERT", или же "SELECT + DELETE" и т.п.
Подобные запросы требуют больше времени на обработку |
POOL_SIZE |
integer (число)
По умолчанию: 2 |
Число потоков для mysql_pquery(). |
SERVER_PORT |
integer (число)
По умолчанию: 3306 |
Порт MySQL сервера |
SSL_ENABLE |
boolean (true/false)
По умолчанию: false (отключено) |
Включение/отключение SSL шифрования |
SSL_KEY_FILE |
string (строка)
Не имеет значения по умолчанию |
Путь к файлу с ключом |
SSL_CERT_FILE |
string (строка)
Не имеет значения по умолчанию |
Путь к файлу сертификата |
SSL_CA_FILE |
string (строка)
Не имеет значения по умолчанию |
Путь к файлу собственного доверенного сертификата |
SSL_CA_PATH |
string (строка)
Не имеет значения по умолчанию |
Путь к каталогу, который содержит доверенные SSL CA сертификаты в PEM формате |
SSL_CIPHER |
string (строка)
Не имеет значения по умолчанию |
Список допустимых шифров для шифрования SSL |
- Данные о подключении, хранящиеся в файле
В MySQL R40 появилась возможность создавать файл, из которого плагин будет брать учётные данные. Для этого в плагине появилась новая функция:
Открыть/закрыть - mysql_connect_file
Описание:
Используется для создания подключения к серверу MySQL и базе данных с помощью INI файла, в котором указаны все учетные данные и опции для соединения
Параметры
PHP код:
(const file_name[] = "mysql.ini")
file_name - имя файла, в котором хранятся данные
Возвращаемое значение:
ID подключения или MYSQL_INVALID_HANDLE, если подключение не удалось
Важно:
Файл с данными обязательно должен находится именно в папке с сервером (где находится "samp-server.exe", "server.cfg" и т.п.)
Пример использования:
PHP код:
new MySQL:mysql_connect_ID;
public OnGameModeInit()
{
mysql_connect_ID = mysql_connect_file(); // Функция будет искать файл "mysql.ini" в коренной папке сервера
return 1;
}
//Содержимое файла опишу ниже
Содержимое файла Для файла есть 4 уникальных настройки:
Настройка |
Описание |
hostname |
IP адрес MySQL сервера (идентично первому параметру в mysql_connect) |
username |
Имя пользователя для авторизации в MySQL сервере (идентично второму параметру в mysql_connect) |
password |
Пароль для авторизации (идентично третьему параметру в mysql_connect) |
database |
Имя базы данных, с которой нужно работать плагину (идентично четвёртому параметру в mysql_connect) |
Так же в данный файл можно записать все опции, таблицу которых я предоставил выше. Отличия опций в функции "mysql_set_option" от опции в файле лишь в том, что в файле имя опции пишется в малом регистре (например, не "SERVER_PORT", а "server_port")
Установка значения происходит с помощью знака "=". Если какую-то настройку нужно оставить пустой (например, пароль), писать в файл её не нужно. Комментарием в файле считается любой текст после ";" или "#".
Пример файла для
этой регистрации:
PHP код:
hostname = localhost ; Адрес хостинга
username = root # имя пользователя
#password = #пароль нам не нужен, поэтому его мы закомментируем
database = sa-mp
#А это пример того, как выглядят настройки
# auto_reconnect = false
# multi_statements = true
; pool_size = 3
; server_port = 3306
Если есть какие-либо вопросы, прошу написать об этом в комментариях.
С вами был DeimoS. Спасибо за внимание :bye:
Автор статьи - DeimoS
Копирование данного материала без разрешения автора запрещено
Интересные статьи на подобную тему:
* [Урок] Создание системы регистрации на основе плагина MySQL [R39/R40]
Цитата:
Сообщение от
Anton Styazhkin
Вышел
MySQL R41. Вот мой немного надуманный перевод :blush2:.
- новая функция mysql_error(): возвращает сообщение об ошибке в последней команде MySQL;
- новая функция mysql_tquery_file(): выполнение всех запросов из файла;
- теперь mysql_query_file() может возвращать кэш со всеми результатами запросов;
- фикс: неправильно определены лог уровни;
- фикс: краш при пустой строке;
- фикс: не работал вызов лога нативно, когда отладочная информация была не доступна;
- фикс: фигурные скобки в аргументах в debug log крашили плагин;
- изменения лог уровня всегда регистрируются;
- пустые строки в mysql_format() больше не будут крашить плагин;
- улучшения/добавления некоторых сообщений в логах;