bus

Материал из RO-fan
Перейти к: навигация, поиск
bus [<булев_флаг>]
Данная переменная позволяет подключаться к bus-шине при старте OpenKore. Если bus-сервер не найден, то он создаётся автоматически. Настройки bus-сервера задаются параметрами: bus_server_host, bus_server_port и bus_userAgent.

Коротко о bus-шине

bus-шина - это специальный протокол, который позволяет различным экземплярам OpenKore легко общаться между собой. Также внешние программы через bus-шину могут общаться с подключенными к ней OpenKore.

bus-шина использует канал связи, который позволяет передавать широковещательные и приватные сообщения. Широковещательные сообщения получат все экземпляры OpenKore, которые подключены к этой шине. Приватное сообщение получит только одна версия OpenKore. Bus можно сравнить с любым мессенджером, где люди могут общаться как в открытых каналах, так и в приватных комнатах.

bus-шина основана на отдельных сообщениях, вместо непрерывной отправки цепочки байт.

bus.png

Запуск bus-сервера

Существует два метода запуска bus-сервера:

  • автоматически запускать его с помощью вашего (первого) экземпляра OpenKore, если настроены соответствующие параметры в sys.txt
  • вручную, из командной строки


Сценарии

  • на одном компе с несколькими запущенными экземплярами OpenKore первый экземпляр запустит bus-сервер. Все остальные экземпляры будут проверять номер порта и подключаться к тому же bus-серверу.
  • если экземпляры OpenKore запускаются на разных компах, то следует вручную запустить bus-сервер, указав определённый порт. Это позволит всем экземплярам OpenKore (сценариям Perl или автономным программам) подключаться к одному и тому же bus-серверу.


Автозапуск bus—сервера

Автозапуск bus-сервера работает одинаково на всех поддерживаемых ОС.

Просто настройте bus 1 в sys.txt для всех экземпляров OpenKore.Первый загруженный экземпляр запустит bus-сервер.

Варианты использования:

  • один комп, много экземпляров OpenKore
  • один комп, один или несколько экземпляров OpenKore, один или несколько автономных Perl скриптов с поддержкой bus-шины запущены на одном компе

Запуск bus-сервера вручную

Ручной запуск - это лучшее решение при использовании нескольких компов в следующих сценариях:

  • экземпляры OpenKore работают на нескольких компьютерах
  • используются автономные perl скрипты, которые запускаются до загрузки OpenKore

В этих случаях, для разрешения различным программам подключаться к bus-серверу, сервер должен быть запущен на заранее заданном хосте и порту. Ниже подробно описаны параметры командной строки и способы загрузки bus-сервера.

Параметры командной строки

Параметры командной строки можно увидеть, запустив скрипт bus-сервера с ключом --help

Параметр Описание
--bind=<host> укажите имя хоста или IP-адрес, который будет прослушивать bus-сервер. Это эквивалент параметра bus_server_host в sys.txt
--port=<номер_порт> Запустить bus-сервер на специальном порту. Если этот параметр пустой, то будет выбран первый доступный порт. Допустимый диапазон: от 1 до 65535.
--quiet НЕ выводить статусные сообщения
--help Показать справку обо всех параметрах


Windows ОС

Большинство пользователей OpenKore в Windows используют для запуска бота консоль (start.exe) или графический Wx_интерфейс (wxstart.exe).

Чтобы запустить bus-сервер с указанным портом, используйте соответствующую команду:

Консоль:start.exe "!" "src/Bus/bus-server.pl" --port=1337

Wx интерфейс:wxstart.exe "!" "src/Bus/bus-server.pl" --port=54321

Пользователи могут либо создать свои bat скрипты, либо изменить ярлык запуска исполняемый файл OpenKore с этими аргументами.

При старте bus-сервера во временной папке "AppData\Local\Temp\" создаётся файл с описанием параметров сервера OpenKore-Bus.info

Unix ОС / OpenKore запускается в интерпретаторе perl

Вы можете запустить bus-сервер из каталога, где находится openkore.pl: yourlogin ~> ./src/Bus/bus-server.pl --port=31416


Описание протокола

Создатель этого протокола назвал формат сообщений "Simple Serializable Message" (SSM). Формат этих сообщений - двоичный.

Каждое сообщение SSM содержит следующую информацию:

  • идентификатор сообщения - MID. Это строка, в которой может быть написано всё, что угодно.
  • список аргументов. Это может быть либо список пар вида параметр-значение (хэш), либо список скалярных значений (массив).

Сообщения очень похожи на вызов функции в языках программирования. Представьте себе следующую функцию в C++:

void copyFile(string from, string to);
copyFile("foo.txt", "bar.txt");

Проводя аналогию между функцией на C++ и сообщением SSM для bus-шины, можно отметить:

  • идентификатор сообщения был бы строкой copyFile;
  • список аргументов состоял бы из двух пар параметр-значение:
from = foo.txt
to = bar.txt

Структура сообщения

Примечание: все целые числа записываются в big-endian. Это означает, что в сообщении старший байт будет записан перед младшим.

Заголовок сообщения

Каждое SSM-сообщение начинается с заголовка struct Header, структура которого описана ниже:

struct {
	// Header
	uint32 length;           // длина всего SSM-сообщения в байтах
	uint8  options;          // тип SSM-сообщения: 0 = список пар параметр-значение, 1 = список скаляров (массив)
	uint8  MID_length;       // длина MID - идентификатора сообщения
	char   MID[MID_length];  // MID - идентификатор сообщения (UTF-8 строка)
} Header;

Если в заголовке сообщения поле options = 0, тогда после заголовка следует список структур struct MapEntry, который идёт до конца SSM-сообщения. Это список пар параметр-значение.

Если в заголовке сообщения поле options = 1, тогда после заголовка следует список структур struct ArrayEntry, который идёт до конца SSM-сообщения. Это список скаляров (массив).

Структура параметр-значение

struct {
	uint8  key_length;           // длина имени параметра
	char   key[key_length];      // имя параметра (UTF-8 строка)

	uint8  value_type;           // тип значения: 0 = двоичный, 1 = UTF-8 строка, 2 = unsigned integer
	uint24 value_length;         // длина значения
	char   value[value_length];  // само значения
} MapEntry;

Структура массива

struct {
	uint8  type;                 // по аналогии MapEntry.value_type
	uint24 length;
	char   value[length];
} ArrayEntry;