wiki:ApiChat

Version 3 (modified by alx, 7 years ago) ( diff )

--

Команда chat

Назначение команды

Команда chat позволяет запрашивать и получать сообщения чата, а также передавать в чат новые сообщения. Чат в блоке MC-4-DSL-3U организован как упорядоченный список сообщений, каждое из которых имеет следующие атрибуты:

  • уникальный идентификатор;
  • время написания;
  • имя пользователя, написавшего сообщение;
  • хост (IP адрес), с которого пользователь передал сообщение;
  • текст сообщения.

Идентификатор сообщения - целое число, увеличивающееся с каждым новым сообщением чата.

Ключи запроса

Ключ Тип значения обязательный Описание
cmd строка да "chat" - имя команды
last число да Идентификатор последнего полученного сообщения или 0 чтобы получить все сообщения.
text строка нет Текст передаваемого в чат сообщения.

Если в запросе присутствует ключ text, то его значение помещается в чат как новое сообщение.

Если ключ last содержит ненулевое значение, в ответ на запрос передаются только те сообщения чата, идентификатор которых больше указанного в поле last значения. Это позволяет запрашивать у сервера только новые сообщения чата.

Если ключ last равен нулю, сервер отдает все сообщения чата. Дополнительно к сообщениям передается ключ me, позволяющий определить, как (под каким именем и с какого адреса) сервер "видит" пользователя, передавшего запрос.

Примеры запроса

{"cmd":"chat","last":0}

{"cmd":"chat","last":1502598091,"text":"Да, я здесь!"}

Права доступа

Для выполнения команды chat не требуется наличия каких-либо прав.

Возвращаемые данные

Ключ Тип значения Описание
cmd строка "chat" - имя команды
me строка Ключ пристствует только если в запросе last=0. Значением является имя пользователя, пославшего запрос, и хост пользователя, пославшего запрос, соединенные символом "@".
messages объект Сообщения чата. Ключи объекта являются идентификаторами сообщений, значениями являются объекты (хэши), каждый из которых описывает одно сообщение чата. Детально формат этих объектов описан ниже.

Обратите внимание, что ключи хэша messages имеют тип "строка", однако в запросе ключ last должен иметь тип "число". Поэтому перед отправкой запроса с указанием идентификатора последнего полученного сообщения значение идентификатора должно быть преобразовано из строки в число.

Формат объекта сообщения чата:

Ключ Тип значения Описание
time число Время написания сообщения (UNIX-time)
user строка Имя пользователя, написавшего сообщение.
host строка Имя хоста пользователя, написавшего сообщение.
text строка Текст сообщения.

Примеры ответов

{
  "cmd":"chat",
  "me":"mike@[192.168.0.75]",
  "messages":{
    "1502598091":{
      "time":1502701826,
      "user":"john",
      "host":"[192.168.0.58]",
      "text":"Михаил, ты здесь?"
    },
    "1502598092":{
      "time":1502701917,
      "user":"mike",
      "host":"[192.168.0.75]",
      "text":"Да, я здесь!"
    }
  }
}

{"cmd":"chat","messages":{}}

Note: See TracWiki for help on using the wiki.