Project

General

Profile

Справочная система по модулям Digispot II » Модули Digispot II » Система событий »

Протокол Digispot Events (XML версия)

Модель

Протокол представляет собой трансляцию в виде XML внутреннего протокола обмена событиями. Используя данный протокол, можно общаться с приложением Digispot II, которое предоставило возможность подключения.

  • протокол описывает общение двух приложений (хостов), установивших между собой связь по протоколу TCP/IP. Соответственно, одно является TCP-сервером, а другое TCP-клиентом. Но эти роли не имеют отношения к данному протоколу, а только к механизму установки связи и процедуре первоначального хендшейка. В дальнейшем обмене данными роли типа клиент и сервер отсутствуют.
  • данные передаются в виде текста в кодировке UTF-8, содержащего XML.
  • каждая XML-посылка терминируется одиночным нулевым байтом, в других местах байты со значением 0 не встречаются никогда.
  • если соединение было разорвано, подключение выполняется повторно, с самого начала.
  • соединение поддерживается постоянно, протокол не требует разрыва соединения. При обрыве TCP-клиент инициирует попытки восстановления связи с сервером.
  • каждый участник по данному протоколу называется хост.
    • между двумя хостами допускается наличие только одного соединения.
    • хост имеет уникальное строчное имя, чувствительное к регистру, уникальное среди всех других хостов данной системы. Правила именования совпадают с правилами именования XML-тегов. Имя хоста не имеет отношения к имени компьютера.
  • один хост может иметь произвольное кол-во соединений другими хостами, причем он может выступать и TCP-сервером и TCP-клиентом одновременно. Но во всех используемых соединениях хост имеет одно и тоже уникальное имя.
  • за исключением хендшейка, все остальные посылки требуют указания получателя.
  • Получатель - это объект, существующий внутри хоста и имеющий уникальный строчный идентификатор, чувствительный к регистру, правила именования совпадают с правилами именования XML тегов. Ближайшая аналогия - tcp-адрес и порт. Порт идентифицирует получателя внутри адреса.
  • формат имени получателя общего вида: /host_name.receiver_name

Формат XML

XML рассматривается как древовидная структура именованных типизированных значений. В каждом теге присутствует атрибут dt, описывающий тип содержимого тега.
dt может быть:

  • i4 - 4 bytes integer
  • i8 - 8 bytes integer
  • f - float
  • b - binary
  • s - string. В этом случае атрибут dt опускается за исключением специальных случаев

Если dt не указан, то тег считается:

  • контейнером
  • строкой, если нет вложенных тэгов, но есть текстовый узел

Тег не может содержать в перемешку текстовые узлы и дочерние тэги одновременно.
Тег верхнего уровня всегда называется .

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

Хендшейк

Хендшейк происходит непосредственно после успешной установки TCP/IP-соединения.

  1. клиент инициировал и установил TCP соединение с сервером.
  2. клиент посылает серверу посылку c указанием имени своего хоста client_name (заменятся реальным именем хоста), и логина и пароля к серверу. Тэги LOGIN и PASSWORD опциональны, и могут быть опущены, если не требуются.
<code class="xml">
<root>
 <Type>HOST</Type>
 <HOST>client_name</HOST>
 <LOGIN>login1</LOGIN>
 <PASSWORD>password1</PASSWORD>
</root>
  1. В ответ должно придти посылка такого вида, с именем удаленного хоста:
<code class="xml">
<root>
 <Type>HOST</Type>
 <HOST>host_name</HOST>
</root>
  1. Хендшейк закончен. Соединение между хостом client_name и хостом host_name установлено. Далее начинается обмен сообщениями, для которых связь собственно и устанавливалась. В случае потери TCP/IP-соединения клиент должен закрыть сокет и перейди к пункту 1.
  2. Если в ответ получено сообщение с другим типом - клиент должен отключиться и начать все сначала.

Типы посылок

В процессе хендшейка и последующего обмена могут передаваться посылки следующих типов.

Type=HOST

Используются при хендшейке.

Type=ERR

Сообщение об ошибке. Может придти в ответ на хендшейк или любого другой пакет.
Содержит единственный тег ERR_STR - с описанием ошибки.

<code class="xml">
<root>
 <Type>ERR</Type>
 <ERR_STR>сообщение об ошибке</ERR_STR>
</root>

Type=EVT

Обычная посылка - событие. Не подразумевает ответа.

  • Обязательные теги:
    • Dst - получатель
      В случае посылки хосту, подключенному к другой стороне сокета, указывается только получатель, без указания имени хоста: receiver, в случае транзитной посылки другому хосту указывается полное имя получателя: /host.receiver
    • Cmd - тип события
    • Src - отправитель
  • Необязательные теги:
    • ARGS - тег, содержащий произвольную XML-структуру дополнительных параметров, уникальную для данного типа Cmd.

Пример:

<code class="xml">
<root>
 <Type>EVT</Type>
 <Cmd>GET_VER</Cmd>
 <Dst>SYS_THR</Dst>
 <Src>Src1</Src>
</root>

Type=ASK

То же, что и Evt, но требующее ответа.
Имеет дополнительный обязательный тег Id - номер данной посылки. В ответ должна придти посылка с типом REP:

<code class="xml">
 <Id dt='i4'>1234</Id>

Type=REP

Ответ на ASK. То же, что и Cmd, но полученное в ответ на ASK
Имеет дополнительный обязательный тег Id - номер посылки, ответ на которую получен.

Широковещательные посылки (NOTIFY)

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

Формат аргументов (ARGS)

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

Add picture from clipboard (Maximum size: 742 MB)