Просмотр кода страницы bus

; bus [<[[References#булев_флаг|булев_флаг]]>]
: Данная переменная позволяет подключаться к 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-сервера работает одинаково на всех поддерживаемых ОС.

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

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

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

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

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

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

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

{| class="wikitable" border="1" cellspacing="0"
|-style=background-color:#F9F9F9;
!Параметр
!Описание
|-
|align=center|--bind=<host>
|укажите имя хоста или IP-адрес, который будет прослушивать bus-сервер. Это эквивалент параметра [[bus_server_host]] в sys.txt
|-
|align=center|--port=<номер_порт>
|Запустить bus-сервер на специальном порту. Если этот параметр пустой, то будет выбран первый доступный порт. Допустимый диапазон: от 1 до 65535.
|-
|align=center|--quiet
|НЕ выводить статусные сообщения
|-
|align=center|--help
|Показать справку обо всех параметрах
|}


==== Windows ОС====

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

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

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

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

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

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

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

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


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

Создатель этого протокола назвал формат сообщений "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

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

Примечание: все целые числа записываются в [https://ru.wikipedia.org/wiki/%D0%9F%D0%BE%D1%80%D1%8F%D0%B4%D0%BE%D0%BA_%D0%B1%D0%B0%D0%B9%D1%82%D0%BE%D0%B2 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;

[[Category:sys.txt]]