CommuniGate Pro: Модуль XIMSS

Клиентское приложение может работать с интерфейсом XIMSS по протоколу HTTP.

Для создания новой сессии XIMSS, клиентское приложение должно отправить HTTP запрос на Вход.

Когда сессия XIMSS создана, клиентское приложение может отправлять в неё запросы протокола XIMSS и получать ответы протокола XIMSS, используя HTTP запросы.

Клиентские приложения могут использовать запросы HTTP GET и POST.
Если запрос содержит тело, то подразумевается, что оно является текстом XML, независимо от действительного значения поля заголовка Content-Type. Текст XML должен быть элементом <XIMSS/>.
Если в результате запроса создаётся непустое тело ответа, то это тело всегда является XML текстом, в котором содержится один элемент <XIMSS/>, а полем заголовка Content-Type является text/xml.

Откройте установки Модуля HTTPU и найдите раздел Доп. протоколов:

Установка Доступ определяет, клиенты из каких сетей могут создавать сессии XIMSS, используя протокол HTTP.

HTTP Вход

Для начала XIMSS сессии, клиентское приложение должно отправить HTTP запрос в модуль HTTPU CommuniGate Pro, используя следующие URL:

http://domainName[:port]/ximsslogin/
или
https://domainName[:port]/ximsslogin/

Если в запросе содержится параметр userName, то Сервер пытается аутентифицировать указанного Пользователя:

Если присутствует параметр password, то используется обычный незашифрованный метод.
Если присутствует параметр nonce, то используется метод CRAM-MD5. Значением параметра "nonce" должно быть действительное значение, полученное с ответом features (смотрите ниже). Запрос должен содержать параметр authData, содержащий "ответ на вызов" CRAM-MD5 в кодировке base64.
Если присутствует параметр sessionid, то используется метод SessionID.
Если указан параметр errorAsXML, а операция входа заканчивается с ошибкой, код ошибки возвращается не как код ответа протокола HTTP, а в виде элемента <response/> с атрибутами errorNum и errorText, заключённого в элемент <XIMSS/>.
Если присутствует параметр version, его значение указывает на версию протокола, используемую клиентом (смотрите параметры операции login).

Если параметр userName отсутствует, то Сервер пытается аутентифицировать запрос, используя TLS Сертификат Клиента (если он задан) или используя методы аутентификации HTTP.
Эта функциональность аналогична используемой в Веб Интерфейсе функциональности Автоматического Вход и Единого Механизма Входа, но здесь используется URL /ximsslogin/.

Запрос на URL /ximsslogin/ может содержать тело text/xml. В этом случае, операция входа не выполняется.
XML тело должно содержать один элемент <XIMSS>, содержащий, в свою очередь, одну или несколько Предшествующие Входу операций XIMSS. Сервер отправляет HTTP ответ с данными XML. Ответом является элемент <XIMSS>, содержащий результаты выполнения затребованных операций.

Пример:

C:GET /ximsslogin/ HTTP/1.1
  Host: myserver.com
  Content-Type: text/xml
  Content-Length: 42

  <XIMSS><listFeatures id="list" /><XIMSS>

S:HTTP/1.1 200 OK
  Content-Length: 231
  Connection: keep-alive
  Content-Type: text/xml;charset=utf-8
  Server: CommuniGatePro/5.3

  <XIMSS><<features id="s" domain="x.domain.dom"><starttls/><sasl>LOGIN</sasl><sasl>PLAIN</sasl><sasl>CRAM-MD5</sasl><sasl>DIGEST-MD5</sasl><sasl>GSSAPI</sasl><nonce>2C3E575E5498CE63574D40F18D00C873</nonce><language>german</language><signup/></features><response id="s"/></XIMSS>

Если пользователь был успешно аутентифицирован и XIMSS сессия была успешно создана, то в ответе на запрос HTTP Входа содержится сообщение session со строкой-идентификатором сессии. Обратите внимание на то, что сообщение session не содержит атрибута id.

Пример:

C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?ackSeq=0 HTTP/1.1
  Host: myserver.com
  Content-Length: 0

S:HTTP/1.1 200 OK
  Content-Length: 105
  Connection: keep-alive
  Content-Type: text/xml;charset=utf-8
  Server: CommuniGatePro/5.3

  <XIMSS><session urlID="562-kAI2lxNBR4ApmHg4wiW9" userName="account@domain" realName="J. Smith" version="6.1.2" /></XIMSS>

Альтернативный URL может использоваться для начала сессии XIMSS посредством TLS Сертификата Клиента или посредством других методов аутентификации HTTP:

http://domainName[:port]/auth/ximsslogin/
или
https://domainName[:port]/auth/ximsslogin/

Этот метод полезен если приложение сначала получает HTML страницу или некоторый другой документ, используя /auth/ область, заставляя браузер запросить полномочия клиента, а затем приложение создаёт XIMSS сессию для этого же пользователя, так как браузер переотправит эти же полномочия при отправке запроса на URL /auth/ximsslogin/.

Синхронные Коммуникации по HTTP

Клиент должен направлять в созданную сессию XIMSS запросы, используя следующие URL:

http://domainName[:port]/Session/sessionID/sync
или
https://domainName[:port]/Session/sessionID/sync

где sessionID является атрибутом urlID сообщения session.

Тело HTTP запроса должно содержать один элемент <XIMSS /> с ноль, одним или более запросами XIMSS протокола.

Сервер возвращает один элемент <XIMSS /> в теле HTTP ответа. Этот элемент содержит сообщения response протокола XIMSS (одно для каждого отправленного XIMSS запроса, в том же порядке); все синхронные сообщения данных созданы в ответ на переданные XIMSS запросы.

Пример:

C:POST /Session/562-kAI2lxNBR4ApmHg4wiW9/sync HTTP/1.1
  Host: myserver.com
  Content-Length: nnn

  <XIMSS><noop id="i1" /><readTime id="i2" /></XIMSS>

S:HTTP/1.1 200 OK
  Content-Length: nnn
  Connection: keep-alive
  Content-Type: text/xml;charset=utf-8
  Server: CommuniGatePro/5.3

  <XIMSS><response id="i1"/><currentTime id="i2" gmtTime="20070502T083313" localTime="20070502T003313"/><response id="i2"/></XIMSS>

Если клиент XIMSS работает в ненадёжной среде, где может быть необходимо посылать запросы HTTP повторно, каждый непустой запрос HTTP должен содержать параметр reqSeq. Значение параметра должно увеличиваться на 1 при посылке каждого нового запроса HTTP.
Если Сервер получает запрос HTTP с таким же значением параметра reqSeq, как в полученном и обработанном ранее запросе HTTP, то Сервер посылает последний ответ повторно (тот же, что был уже послан в ответ на предыдущий запрос HTTP с тем же reqSeq).
Если Сервер получает запрос HTTP со значением параметра reqSeq, которое не равно значению reqSeq предыдущего запроса и не равно увеличенному на 1 значению reqSeq предыдущего запроса, то Сервер возвращает ошибку.

Клиентское приложение может использовать "пустой запрос" (HTTP запрос без тела) для того, чтобы прочитать асинхронные сообщения данных XIMSS.

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

для этой сессии генерируется асинхронное сообщение данных; или
время ожидания закончилось; или
получен новый "пустой запрос"; или
сессия закрывается.

Пустой запрос может задавать время ожидания в параметре maxWait (число секунд).

Если сообщения данных не были получены, то Сервер отправляет ответ с пустым элементом <XIMSS/>, без каких-либо атрибутов.

Если были получены какие-либо сообщения данных, то Сервер отправляет ответ ("асинхронный ответ"), содержащий один элемент <XIMSS/> с атрибутом respSeq. Этот атрибут содержит последовательный номер для этого элемента <XIMSS/> ответа.

Сервер хранит последний "асинхронный ответ", сформированный для каждой сессии.

Каждый пустой запрос должен содержать параметр ackSeq. В нём должно находится значение respSeq из последнего полученного асинхронного ответа.
Если клиент не получал ещё никаких асинхронных ответов, то значение этого параметра должно быть 0.

Когда Сервер получает пустой запрос со значением ackSeq равным значению respSeq последнего хранимого сформированного асинхронного ответа, то он считает доставку этого ответа "подтверждённой" и удаляет его.

Когда Сервер получает пустой запрос со значением ackSeq равным значению respSeq последнего хранимого сформированного асинхронного ответа, уменьшенного на единицу (respSeq-1), и последний сформированный ответ все ещё хранится, то Сервер отправляет этот ответ клиенту повторно. В результате, если клиент сталкивается с ошибкой при передаче во время выполнения HTTP транзакции "пустого запроса", то он может отправить пустой запрос повторно.

Пустой запрос без параметра ackSeq подтверждает получение всех хранимых сформированных "асинхронных ответов".

Когда сервер возвращает пустой элемент <XIMSS/>, следующий пустой запрос может либо не содержать параметр ackSeq совсем, либо тот же параметр ackSeq, как в последнем пустом запросе. Поскольку последующие пустые запросы могут использовать всё тот же URL запроса с теми же параметрами, платформа клиента может немедленно возвращать закешированный ранее элемент <XIMSS/> без фактической отправки запроса на Сервер.
Во избежание этой проблемы в каждый пустой запрос нужно включать параметр reqSeq, значение которого увеличивается после каждой успешной транзакции.

Пример:

C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=90&ackSeq=0&reqSeq=0 HTTP/1.1
  Host: myserver.com
  Content-Length: 0

...необязательная пауза (до 90 секунд)...
S:HTTP/1.1 200 OK
  Content-Length: 10
  Connection: keep-alive
  Content-Type: text/xml;charset=utf-8
  Server: CommuniGatePro/5.3

  <XIMSS/>
C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=90&ackSeq=0&reqSeq=1 HTTP/1.1
  Host: myserver.com
  Content-Length: 0

...необязательная пауза (до 90 секунд)...
S:HTTP/1.1 200 OK
  Content-Length: nnn
  Connection: keep-alive
  Content-Type: text/xml;charset=utf-8
  Server: CommuniGatePro/5.3

  <XIMSS respSeq="1"><folderReport folder="INBOX" mode="notify" /></XIMSS>
response did not reach the client, client is resending the request
C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=90&ackSeq=0&reqSeq=1 HTTP/1.1
  Host: myserver.com
  Content-Length: 0

S:HTTP/1.1 200 OK
  Content-Length: nnn
  Connection: keep-alive
  Content-Type: text/xml;charset=utf-8
  Server: CommuniGatePro/5.3

  <XIMSS respSeq="1"><folderReport folder="INBOX" mode="notify" /></XIMSS>
C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=90&ackSeq=1&reqSeq=2 HTTP/1.1
  Host: myserver.com
  Content-Length: 0

...необязательная пауза (до 90 секунд)...
S:HTTP/1.1 200 OK
  Content-Length: 10
  Connection: keep-alive
  Content-Type: text/xml;charset=utf-8
  Server: CommuniGatePro/5.3

  <XIMSS/>

Асинхронные Коммуникации по HTTP

Клиент может отправлять запросы в созданную XIMSS сессию таким образом, что все ответы (включая сообщения response и синхронные сообщения данных) будут возвращаться только в ответ на "пустой запрос".

http://domainName[:port]/Session/sessionID/async
или
https://domainName[:port]/Session/sessionID/async

где sessionID является атрибутом urlID сообщения session.

Тело запроса HTTP должно содержать один элемент <XIMSS /> с ноль, одним или более запросами протокола XIMSS.

Все генерируемые сообщения response (по одному для каждого запроса XIMSS, отправляемые в том же порядке) и все синхронные сообщения данных, созданные в ответ на переданные XIMSS запросы, передаются повторно в XIMSS сессию как асинхронные сообщения. Сервер возвращает пустой ответ HTTP.

Пример (одно соединение, опрос):

C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=0&ackSeq=0&reqSeq=0 HTTP/1.1
  Host: myserver.com
  Content-Length: 0

S:HTTP/1.1 200 OK
  Content-Length: 10
  Connection: keep-alive
  Content-Type: text/xml;charset=utf-8
  Server: CommuniGatePro/5.3

  <XIMSS/>
C:POST /Session/562-kAI2lxNBR4ApmHg4wiW9/async HTTP/1.1
  Host: myserver.com
  Content-Length: nnn

  <XIMSS><noop id="i1" /><readTime id="i2" /></XIMSS>
S:HTTP/1.1 200 OK
  Content-Length: 0
  Connection: keep-alive
  Content-Type: text/plain;charset=utf-8
  Server: CommuniGatePro/5.3

C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=0&ackSeq=0&reqSeq=1 HTTP/1.1
  Host: myserver.com
  Content-Length: 0

S:HTTP/1.1 200 OK
  Content-Length: nnn
  Connection: keep-alive
  Content-Type: text/xml;charset=utf-8
  Server: CommuniGatePro/5.3

  <XIMSS respSeq="1"><response id="i1"/><currentTime id="i2" gmtTime="20070502T083313" localTime="20070502T003313"/><response id="i2"/></XIMSS>

Пример (2 соединения, ожидание):

C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?ackSeq=0&reqSeq=0 HTTP/1.1
  Host: myserver.com
  Content-Length: 0

...ожидание...

S:HTTP/1.1 200 OK
  Content-Length: nnn
  Connection: keep-alive
  Content-Type: text/xml;charset=utf-8
  Server: CommuniGatePro/5.3

  <XIMSS respSeq="1">
    <response id="i1"/>
    <currentTime id="i2" gmtTime="20070502T083313"
      localTime="20070502T003313"/>
    <response id="i2"/>
  </XIMSS>
C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?ackSeq=1&reqSeq=1 HTTP/1.1
  Host: myserver.com
  Content-Length: 0

...ожидание...

C:POST /Session/562-kAI2lxNBR4ApmHg4wiW9/async HTTP/1.1
  Host: myserver.com
  Content-Length: nnn

  <XIMSS><noop id="i1" /><readTime id="i2" /></XIMSS>
S:HTTP/1.1 200 OK
  Content-Length: 0
  Connection: keep-alive
  Content-Type: text/xml;charset=utf-8
  Server: CommuniGatePro/5.3

Модуль XIMSS

Настройка Модуля XIMSS

Соединения XIMSS с Другими Модулями

Безопасность Flash Клиентов

Сессии XIMSS

Привязка к HTTP

HTTP Вход

Синхронные Коммуникации по HTTP

Асинхронные Коммуникации по HTTP

Мониторинг активности XIMSS