Total Kontrol/TKT/Протокол обмена с демоном

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

Протокол однонаправленный, от страницы к демону. На любое действие пользователя страница формирует событие. При отсутствии событий страница отправляет запросы на обновление через заданный промежуток времени (атрибут refresh элемента daemon).

Пакет представляет собой серию текстовых строк, завершаемую пустой строкой (два CRLF в конце пакета). После передачи любого пакета (событие или обновление) страница не закрывает соединение, демон передаёт данные обновления состояния видимых элементов и закрывает соединение сам. Страница закрывает соединение при отсутствии ответа от демона в течение периода eventrate страницы (атрибут элемента daemon).

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

<id видимого элемента><CRLF>
<количество параметров><CRLF>
<параметр 1><CRLF>
....
<параметр n><CRLF>

Количество и назначение каждого параметра определяется типом видимого элемента (см. Формат XML файла). Количество кадров в пакете не ограничено.

Обновления

Для экономии трафика обновления привязываются ко времени. Клиент (открытая в браузере страница) передаёт серверу (демону) запрос на обновление с указанием времени предыдущего обновления в миллисекундах (чтобы демон знал, какие именно обновления нужно передать именно этому клиенту), и имя страницы (чтобы демон не обновлял все страницы). Пакет запроса на обновление:

UPDATE <время> <id страницы><CRLF>
<CRLF>

Время - внутренний счётчик демона, он отдаёт его значение с каждым пакетом данных обновления. Если страница только что открылась - она передаёт демону время 1, демон обновляет всё что есть.

Ответ демона начинается со строки с текущим счётчиком времени, затем (при наличии необновлённых данных) следуют кадры обновления.

События

Для исключения перегрузки клиентской машины, сервера и локальной сети частота отправки событий ограничивается атрибутом eventrate элемента daemon. В период ожидания после отправки события страница не формирует новые события, но отслеживает изменения состояния элементов, по истечении периода ожидания отправляет событие с состоянием изменившихся элементов на момент отправки. Как и обновления, пакет события может содержать кадры для нескольких видимых элементов, с которыми произошли события за период ожидания. Пакет события:

EVENT<CRLF>
<кадр>
[<кадр>]
[...   ]
[<кадр>]
<CRLF>

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

Обмен данными

Отличается от 1.0 тем, что все клиенты поддерживают с сервером постоянное соединение. Кроме того, добавлена система идентификации клиентских устройств. Обмен данными для видимых элементов остался прежним, добавились только средства идентификации. Для зарегистрированных клиентов после слова EVENT через двоеточие указываются номера клиентов. Механизм eventrate сохраняется. Сохраняется возможность работы клиентских устройств без регистрации, аналогично версии 1.0 (id клиента в обмене не указываются).

Пакет события выглядит следующим образом (в одном пакете - строго одно событие от одного управляющего элемента):

EVENT[:клиент]<CRLF>
<id элемента><CRLF>
<кол-во параметров><CRLF>
<параметр 1><CRLF>
...
<параметр n><CRLF>
<CRLF>

Постоянное соединение отменяет необходимость в циклическом опросе со стороны клиентов: демон сам выдаёт обновления видимых элементов в нужный момент. В отличии от версии 1.0, каждый пакет обновления демон предваряет строкой UPDATE, в которой аналогично EVENT может быть указан номер клиента или группа клиентов (UPDATE:G1). Предопределена группа 0 - все зарегистрированные клиенты. UPDATE без указания id клиента или группы рассылается сервером всем подключенным клиентам (не только зарегистрированным).

Пакет обновления, в отличие от версии 1.0, может содержать данные только для одного видимого элемента:

UPDATE[:клиент|:группа]<CRLF>
<id элемента><CRLF>
<кол-во параметров><CRLF>
<параметр 1><CRLF>
...
<параметр n><CRLF>
<CRLF>

Сервер может отправить демону запрос на обновление в случае, когда клиент подключился к серверу:

UPDATE[:клиент]<CRLF>
<CRLF>

Если клиент является членом одной или нескольких групп, сервер отправляет аналогичные запросы обновлений для каждой группы, в которую включен клиент.

Идентификация клиентов

Клиент регистрируется на сервере веб-интерфейса однократно, вручную, открытием URL веб-интерфейса с параметром ?setid=<id>. Если вместо <id> указать delete - привязка удаляется. Если поступает запрос на привязку к id, который уже есть в базе - старая привязка удаляется, к этому id привязывается новый клиент. Регистрация в группе - аналогично, ?setgroup=<id>. Идентификаторы клиентов и групп могут быть только числовыми. Предопределена группа 0 - все зарегистрированные клиенты, удалить клиента из неё нельзя. Один клиент может быть членом неограниченного числа групп.

Кэш обновлений

Сервер хранит все обновления от демона в течение заданного времени t. В случае, если какой-либо из зарегистрированных клиентов в момент получения пакета от демона отключен, сервер переводит клиента в состояние временно отпавшего. Если клиент не появляется на связи в течение времени t, клиент переводится в состояние совсем отпавшего. При подключении клиент передаёт запрос обновления серверу, если время его отключения не превысило t - сервер переводит его в штатный режим и отправляет ему обновления из кэша, если клиент был оффлайн дольше, т. е. какие-то обновления могли потеряться - для него запрашивается полное обновление, как при первом подключении.

Проверка связи

Для поддержания постоянного соединения сервер (апач) может отправлять демону пакет PING<CRLF><CRLF>, демон отвечает PONG<CRLF><CRLF>.

Пакеты обновления видимых элементов

В пакете обновления видимого элемента первая строка - всегда видимое состояние, может принимать одно из определённых в xml числовых значений, invisible и unavailable (состояние unavailable также должно быть определено в xml). Передача видимого состояния, не определённого в xml, игнорируется.

pushbutton

Один параметр, определяющий состояние кнопки. Состояние может принимать числовые значения, unavailable, invisible. Пример (кнопка button1 переводится в недоступное состояние):

button1<CRLF>
1<CRLF>
unavailable<CRLF>
<CRLF>

checkbox

Один параметр, определяющий состояние кнопки. Состояние может принимать числовые значения, unavailable, invisible. Пример (кнопка button2 переводится в «нажатое» состояние):

button2<CRLF>
1<CRLF>
1<CRLF>
<CRLF>

radiogroup

Три варианта пакета обновления. Первый: один параметр, принимающий значения invisible, unavailable или номер активной кнопки. Состояния видимости и доступности влияют на все кнопки в группе. Пример (в группе rgroup1 активируется кнопка 3):

rgroup1<CRLF>
1<CRLF>
3<CRLF>
<CRLF>

Второй вариант - пакет обновления аналогичен первому, единственный параметр может принимать значения invisible, unavailable и 0, все остальные игнорируются. ID пакета обновления формируется из ID группы с добавлением значения кнопки через слэш. Пример (в группе rgroup1 кнопка 2 исчезает):

rgroup1/2<CRLF>
1<CRLF>
invisible<CRLF>
<CRLF>

Третий вариант - в одном пакете передаётся значение активной кнопки, после чего передаются состояния всех кнопок группы в том порядке, в котором кнопки описаны в xml. Пример (для группы rgroup1 из 4х кнопок с значениями 1-4, тот же эффект, что предыдущие 2 примера):

rgroup1<CRLF>
5<CRLF>
3<CRLF>
0<CRLF>
invisible<CRLF>
0<CRLF>
0<CRLF>
<CRLF>

slider/rocker

Один параметр, определяющий положение спрайта, либо unavailable/invisible. В состоянии unavailable спрайт не отображается. Пример (полная шкала, спрайт в положении 30%):

slider1<CRLF>
1<CRLF>
21845<CRLF>
<CRLF>

pad/joystick

Три параметра: видимое состояние (0/unavailable/invisible), X спрайта, Y спрайта. В состоянии unavailable спрайт не отображается. Пример (спрайт по центру):

pad1<CRLF>
3<CRLF>
0<CRLF>
32768<CRLF>
32768<CRLF>
<CRLF>

input/lightbox

Один (видимое состояние) или два (видимое состояние и текст) параметра. Пример (состояние 3, текст):

lightbox1<CRLF>
2<CRLF>
3<CRLF>
ХУЙ<CRLF>
<CRLF>

movie

Один параметр - источник изображения либо invisible. Пример (источник 3):

video1<CRLF>
1<CRLF>
3<CRLF>
<CRLF>

dropdown

Два варианта: один параметр - текущий выбор, более одного - обновление списка. Первый параметр всегда выбор/invisible/unavailable/open. Open - принудительное открытие списка. Пример (перезагрузка списка и открытие для выбора):

list_weekend<CRLF>
open<CRLF>
Водка<CRLF>
Пиво<CRLF>
Бабы<CRLF>
Преферанс<CRLF>
И на карусельке покататься<CRLF>
<CRLF>

proxy

Два варианта аналогично dropdown, только вместо строк - URL'ы. Первый параметр всегда выбор/invisible/unavailable.

list

Первый параметр - видимое состояние, остальные - строки для отображения:

list_queue<CRLF>
4<CRLF>
0<CRLF>
Иванов И. И.<CRLF>
Петров П. П.<CRLF>
Затыкьян З. З.<CRLF>
<CRLF>