| | 1 | = Команда chat = |
| | 2 | |
| | 3 | == Назначение команды == |
| | 4 | |
| | 5 | Команда `chat` позволяет запрашивать и получать сообщения чата, а также передавать в чат новые сообщения. Чат в блоке MC-4-DSL-3U организован как упорядоченный список сообщений, каждое из которых имеет следующие атрибуты: |
| | 6 | * уникальный идентификатор; |
| | 7 | * время написания; |
| | 8 | * имя пользователя, написавшего сообщение; |
| | 9 | * хост (IP адрес), с которого пользователь передал сообщение; |
| | 10 | * текст сообщения. |
| | 11 | |
| | 12 | Идентификатор сообщения - целое число, увеличивающееся с каждым новым сообщением чата. |
| | 13 | |
| | 14 | == Ключи запроса == |
| | 15 | |
| | 16 | || '''Ключ''' || '''Тип значения''' || '''обязательный''' || '''Описание''' || |
| | 17 | || cmd || строка || да || "chat" - имя команды || |
| | 18 | || last || число || да || Идентификатор последнего полученного сообщения или 0 чтобы получить все сообщения. || |
| | 19 | || text || строка || нет || Текст передаваемого в чат сообщения. || |
| | 20 | |
| | 21 | Если в запросе присутствует ключ `text`, то его значение помещается в чат как новое сообщение. |
| | 22 | |
| | 23 | Если ключ `last` содержит ненулевое значение, в ответ на запрос передаются только те сообщения чата, идентификатор которых больше указанного в поле `last` значения. Это позволяет запрашивать у сервера только новые сообщения чата. |
| | 24 | |
| | 25 | Если ключ `last` равен нулю, сервер отдает все сообщения чата. Дополнительно к сообщениям передается ключ `me`, позволяющий определить, как (под каким именем и с какого адреса) "видит" сервер пользователя, передавшего запрос. |
| | 26 | |
| | 27 | === Примеры запроса === |
| | 28 | |
| | 29 | `{"cmd":"chat","last":0}` |
| | 30 | |
| | 31 | `{"cmd":"chat","last":1502598091,"text":"Да, я здесь!"}` |
| | 32 | |
| | 33 | == Права доступа == |
| | 34 | |
| | 35 | Для выполнения команды `certinfo` не требуется наличия каких-либо прав. |
| | 36 | |
| | 37 | == Возвращаемые данные == |
| | 38 | |
| | 39 | || '''Ключ''' || '''Тип значения''' || '''Описание''' || |
| | 40 | || cmd || строка || "chat" - имя команды || |
| | 41 | || me || строка || Ключ пристствует только если в запросе last=0. Значением является имя пользователя, пославшего запрос, и хост пользователя, пославшего запрос, соединенные символом "@". || |
| | 42 | || messages || объект || Сообщения чата. Ключи объекта являются идентификаторами сообщений, значениями сообщений являются объекты (хэши), каждый из которых описывает одно сообщение чата. Детально формат этих объектов описан ниже. || |
| | 43 | |
| | 44 | Обратите внимание, что ключи хэша `messages` имеют тип "строка", однако в запросе ключ `last` должен иметь тип "число". Поэтому перед отправкой запроса с указанием идентификатора последнего полученного сообщения значение идентификатора должно быть преобразовано из строки в число. |
| | 45 | |
| | 46 | Формат объекта сообщения чата: |
| | 47 | |
| | 48 | || '''Ключ''' || '''Тип значения''' || '''Описание''' || |
| | 49 | || time || число || Время написания сообщения (UNIX-time) || |
| | 50 | || user || строка || Имя пользователя, написавшего сообщение. || |
| | 51 | || host || строка || Имя хоста пользователя, написавшего сообщение. || |
| | 52 | || text || строка || Текст сообщения. || |
| | 53 | |
| | 54 | === Примеры ответов === |
| | 55 | |
| | 56 | {{{ |
| | 57 | { |
| | 58 | "cmd":"chat", |
| | 59 | "me":"mike@[192.168.0.75]", |
| | 60 | "messages":{ |
| | 61 | "1502598091":{ |
| | 62 | "time":1502701826, |
| | 63 | "user":"john", |
| | 64 | "host":"[192.168.0.58]", |
| | 65 | "text":"Михаил, ты здесь?" |
| | 66 | }, |
| | 67 | "1502598092":{ |
| | 68 | "time":1502701917, |
| | 69 | "user":"mike", |
| | 70 | "host":"[192.168.0.75]", |
| | 71 | "text":"Да, я здесь!" |
| | 72 | } |
| | 73 | } |
| | 74 | } |
| | 75 | }}} |
| | 76 | |
| | 77 | `{"cmd":"chat","messages":{}}` |
