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

MMP - протокол соединения Mail.Ru Агента с общей сетью Mail.Ru. Рекомендованный для соединения сервер в любой момент времени можно получить в текстовом формате ip:port по адресу mrim.mail.ru:443 и mrim.mail.ru:2042. Взаимодействие с сервером происходит поверх постоянно установленного tcp-соединения посредством асинхронного обмена командами. Инициатором установления соединения может быть только клиент, команды могут посылаться как клиентом, так и сервером.

MMP бинарный протокол. Все числовые данные передаются как четырехбайтные целые НЕ в сетевом формате, т. е. первым идет старший байт, последним младший. Четырехбайтовые беззнаковые целые обозначаются UL.

Текстовые данные передаются с префексированной длиной, т. е. сначала UL, а потом строка (в кодировке windows-1251) длины UL без завершающего нуля. Обозначение в дальнейшем - LPS.

Тип данных UIDL используется только при работе с оставленными на сервере сообщениями. UIDL - последовательность из 8 символов из множества [a-z A-Z 0-9 _ - = +].

Каждая команда или ответ на нее начинаются с заголовка. Поля указываемые в заголовке:

• волшебный ключ, указывающий на то, что это действительно пакет MMP - версия MMP, поддерживаемая отправителем пакета (текущая версия - 1.7)
• номер отправляемой команды в текущем соединении. Ответ на команду должен иметь тот же номер, что и сама команда.
• тип пакета, номер команды и/или ответа
• длинна данных пакета (без учета заголовка). При обработке посылаемых сервером данных длина пакета должна иметь приоритет перед списком его параметров, т. к. в следующих версиях протокола могут появляться новые параметры и все они будут дописываться в конец пакета.
• порт и ip (в inet_aton() формате) с которых установлено соединение

В синтаксисе языка С:

Заголовок пакета
{
    u_long	magic;
    u_long	proto;
    u_long	seq;
    u_long	msg;
    u_long	dlen;
    u_long	from;
    u_long	fromport;
    u_char	reserved[16];
}

Вам понадобится заголовочный файл на языке C. Взять его можно здесь.

Последовательность команд

После установки tcp-соединения клиент обязан сразу послать MRIM_CS_HELLO, дождаться MRIM_CS_HELLO_ACK, после чего отправить MRIM_CS_LOGIN2 и начать посылать MRIM_CS_PING с установленным в MRIM_CS_HELLO_ACK интервалом. В случае успешной авторизации дальнейшие пакеты (кроме MRIM_CS_PING) должны отправляться только в случае пользовательских действий (написания новых сообщений и т. п.) или ответа на пакеты получаемые от сервера.

Типы пакетов

Тип пакета: cs - Client -> Server
Тип пакета: sc - Server -> Client

Пакеты

• Пакет: Установка соединения

  Имя пакета: MRIM_CS_HELLO
  Ответ: MRIM_CS_HELLO_ACK
  Тип пакета: cs
  Описание: Первый пакет, отправляемый на сервер.

• Пакет: Подтверждение установки соединения

  Имя пакета: MRIM_CS_HELLO_ACK
  Тип пакета: sc
  Параметры:

  UL ## ping_period ## Ожидаемая частота подтверждения соединения (в секундах)

  Описание: Подтверждает возможность соединения и сообщает клиенту интервал, с которым надо отправлять пакеты контроля соединения.

• Пакет: Успешная авторизация

  Имя пакета: MRIM_CS_LOGIN_ACK
  Тип пакета: sc
  Описание: Сообщает, что пара логин-пароль была верна и клиент успешно авторизовался в сети агента.

• Пакет: Неверная авторизация

  Имя пакета: MRIM_CS_LOGIN_REJ
  Тип пакета: sc
  Параметры:

  LPS ## reason ## причина отказа

  Описание: Сообщает, что пара логин-пароль была неверна, и соединение будет завершено.

• Пакет: Контроль соединения

  Имя пакета: MRIM_CS_PING
  Тип пакета: cs
  Описание: Отправка этого пакета подтверждает для сервера, что клиент активен. Пакет должен отправляться с интервалом, определенным в MRIM_CS_HELLO_ACK.

• Пакет: Сообщение

  Имя пакета: MRIM_CS_MESSAGE
  Тип пакета: cs
  поле seq должно содержать номер, который в последствии будет содержаться в заголовке пакета MRIM_CS_MESSAGE_STATUS, оповещающем клиента о статусе доставки данного сообщения.
  Параметры:

  UL ## flags ## флаги ##

  MESSAGE_FLAG_OFFLINE ## Сообщение пришло, пока клиент был отключен
  MESSAGE_FLAG_NORECV ## Отправителю сообщения не требуется подтверждения доставки
  MESSAGE_FLAG_AUTHORIZE ## Сообщение является запросом на авторизацию
  MESSAGE_FLAG_SYSTEM ## Сообщение является системным уведомлением администрации
  MESSAGE_FLAG_RTF ## В сообщении содержится форматированная часть
  MESSAGE_FLAG_CONTACT ## Сообщение представляет из себя пересланный список контактов. Текст сообщения в этом случае должен представлять из себя список адресов и ников пересылаемых контактов, перечисленных через точку с запятой. <адрес1>;<ник1>;<адрес2>;<ник2>;<адрес3>;<ник3>;...
  MESSAGE_FLAG_NOTIFY ## Это сообщение-уведомление "Вам пишут". Должно посылаться каждые 10 секунд, при более длинной паузе клиент-получатель должен считать, что отправитель прекратил написание. Текст такого сообщения должен состоять из одного пробела.
  MESSAGE_FLAG_MULTICAST ## Сообщение направлено списку получателей, а не одному. Поле to в таком случае состоит из списка получателей, перечисленных через запятую. Максимальная длина списка - 50 адресов.

  LPS ## to ## email получателя
  LPS ## message ## текстовая версия отправляемого сообщения
  LPS ## rtf-message ## отформатированная версия отправляемого сообщения, в случае наличия обоих версий сообщения приоритет имеет rtf-версия. Она должна содержать rtf-текст упакованный gzip в base64 представлении. То есть:

  BASE64(
    		GZIP(
    			UL количество LPS (должно быть не менее 2)
    			LPS rtf_text_with_all_rtf_headers_and_tags
    			LPS цвет фона в виде UL
   			 )
   		 )
  					

  Описание: Основной пакет взаимодействия между двумя клиентами. Может быть отправлено в любой момент по инициативе клиента. Ни текстовая, ни rtf части сообщений не могут быть пустыми, при необходимости следует использовать строку из одного пробела.

• Пакет: Доставка сообщения

  Имя пакета: MRIM_CS_MESSAGE_ACK
  Тип пакета: sc
  Параметры:

  UL ## msg_id ## Номер пакета (Sequence) этого сообщения для отправителя
  UL ## flags ## Возможные значения описаны в MRIM_CS_MESSAGE
  LPS ## from ## Адрес отправителя
  LPS ## message ## текстовая версия сообщения
  LPS ## rtf-message ## форматированная версия сообщения

  Описание:

• Пакет: Подтверждение получения сообщения

  Имя пакета: MRIM_CS_MESSAGE_RECV
  Тип пакета: cs
  Параметры:

  LPS ## from ##
  UL ## msg_id ##

  Описание: Отправляется получателем сообщения сразу после прихода MRIM_CS_MESSAGE_ACK, если флаги MRIM_CS_MESSAGE_ACK не содержали MESSAGE_FLAG_NORECV. from и msg_id должны быть скопированы из MRIM_CS_MESSAGE_ACK и имеют то же значение.

• Пакет: Подтверждение доставки сообщения

  Имя пакета: MRIM_CS_MESSAGE_STATUS
  Тип пакета: sc
  Поле seq численно равно полю seq пакета MRIM_CS_MESSAGE
  Параметры:

  UL ## status ## статус доставки ##

  MESSAGE_DELIVERED ## Сообщение успешно доставлено
  MESSAGE_REJECTED_INTERR ## Произошла внутренняя ошибка
  MESSAGE_REJECTED_NOUSER ## Не существует пользователя-получателя сообщения
  MESSAGE_REJECTED_LIMIT_EXCEEDED ## Пользователь-получатель в данный момент отключен от сети, и сообщение не помещается в его почтовый ящик
  MESSAGE_REJECTED_TOO_LARGE ## Размер сообщения превышает максимально допустимый
  MESSAGE_REJECTED_DENY_OFFMSG ## Пользователь-получатель в данный момент отключен от сети, а настройки его почтового ящика не допускают наличие оффлайновых сообщений агента

  Описание: Отправленное сообщение считается доставленным только после получения этого ответа сервера. Сервер НЕ ГАРАНТИРУЕТ доставку сообщения. В случае отстутствия MRIM_CS_MESSAGE_STATUS более интервала подтверждения соединения, программа клиент должна послать сообщение повторно или проинформировать пользователя о невозможности доставки из-за проблем связи получателя.

• Пакет: Смена статуса другого пользователя

  Имя пакета: MRIM_CS_USER_STATUS
  Тип пакета: sc
  Параметры:

  UL ## status ## новый статус пользователя ##

  STATUS_OFFLINE ## Пользователь отключен от сети Агента
  STATUS_ONLINE ## Пользователь находится в сети
  STATUS_AWAY ## Пользователь в сети, но отошел от компьютера
  STATUS_UNDETERMINATED ## Настройки пользователя запрещают показывать его статус
  STATUS_FLAG_INVISIBLE ## Пользователь находится в сети, но невидим для всех, кроме привилегированных пользователей из его списка видимости.

  LPS ## user ## email сменившего свой статус пользователя

  Описание: Это сообщение отправляется сервером при смене статуса пользователям всем тем, у кого он находится в контакт-листе (за исключением группы "Жду Авторизации" и тех, кого он включил в список игнорируемых или невидящих). Данное сообщение может быть доставлено клиенту ДО получения им контакт-листа. В такой ситуации оно должно игнорироваться.

• Пакет: Закрытие соединения

  Имя пакета: MRIM_CS_LOGOUT
  Тип пакета: sc
  Параметры:

  UL ## reason ## причина отключения ##

  LOGOUT_NO_RELOGIN_FLAG ## Пользователь отключен из-за параллельного входа с его логином. Клиент не должен осуществлять автоматический перезаход в этом случае.

• Пакет: Изменение параметров соединения

  Имя пакета: MRIM_CS_CONNECTION_PARAM
  Тип пакета: sc
  Параметры:

  UL ## ping_period ## новая ожидаемая частота подтверждения соединения

  Описание: Ближайший MRIM_CS_PING следует отправлять уже исходя из новой частоты.

• Пакет: Добавление нового контакта

  Имя пакета: MRIM_CS_ADD_CONTACT
  Тип пакета: cs
  Параметры:

  UL ## flags ## флаги ##

  CONTACT_FLAG_GROUP ## Добавляется новая группа, а не контакт (несовместим с остальными). Верхний байт содержит количество уже имеющихся групп в контакт-листе
  CONTACT_FLAG_INVISIBLE ## Контакт должен попасть в список "Я всегда невидим для"
  CONTACT_FLAG_VISIBLE ## Контакт должен попасть в список "Я всегда видим для"
  CONTACT_FLAG_IGNORE ## Контакт должен попасть в список игнорируемых
  CONTACT_FLAG_SHADOW ## Контакт не должен попасть в основной контакт-лист (применяется в паре с одним из трех предыдущих)
  CONTACT_FLAG_REMOVED ## Контакт удален

  UL ## group_id ## группа, в которую должен быть добавлен контакт (для CONTACT_FLAG_GROUP равно 0)
  LPS ## email ## добавляемый адрес (имя группы для CONTACT_FLAG_GROUP)
  LPS ## name ## ник добавляемого пользователя (для отображения в контакт-листе, не посылается для CONTACT_FLAG_GROUP) LPS ## unused ## неиспользуемый параметр

• Пакет: Подтверждение добавления контакта

  Имя пакета: MRIM_CS_ADD_CONTACT_ACK
  Тип пакета: sc
  Параметры:

  UL ## status ## результат операции ##

  CONTACT_OPER_SUCCESS ## добавление произведено успешно
  CONTACT_OPER_ERROR ## переданные данные были некорректны
  CONTACT_OPER_INTERR ## при обработке запроса произошла внутренняя ошибка
  CONTACT_OPER_NO_SUCH_USER ## добавляемого пользователя не существует в системе
  CONTACT_OPER_INVALID_INFO ## некорректное имя пользователя
  CONTACT_OPER_USER_EXISTS ## пользователь уже есть в контакт-листе
  CONTACT_OPER_GROUP_LIMIT ## превышено максимально допустимое количество групп (20)

  ## UL ## contact_id ## присвоенный новому контакту номер

  Описание: Приходит в ответ на MRIM_CS_ADD_CONTACT. -1 если status не равен CONTACT_OPER_SUCCESS.

• Пакет: Изменение контакта

  Имя пакета: MRIM_CS_MODIFY_CONTACT
  Тип пакета: cs
  Параметры:

  UL ## id ## номер модифицируемого контакта
  UL ## flags ##
  UL ## group_id ## Равно 0 для группы
  LPS ## contact ## Если группа, то имя группы
  LPS ## name ## Если группа, то имя группы

  Описание: Параметры те же, что и у MRIM_CS_ADD_CONTACT. contact до и после изменения обязаны совпадать.

• Пакет: Подтверждение изменения контакта

  Имя пакета: MRIM_CS_MODIFY_CONTACT_ACK
  Тип пакета: sc
  Параметры:

  UL ## status ## Результат операции. Значения имеют тот же смысл, что и в MRIM_CS_ADD_CONTACT_ACK

• Пакет: Сообщение доставленное, пока пользователь не был подключен к сети

  Имя пакета: MRIM_CS_OFFLINE_MESSAGE_ACK
  Тип пакета: sc
  Параметры:

  UIDL ## uidl ## id сообщения
  LPS ## message ## сообщение. Сообщение приходит в формате RFC/822 письма. Отправитель сообщения хранится в заголовке From, дата в заголовке Date, флаги сообщения в X-MRIM-FLAGS, текстовая и форматированная версии сообщения составляют текст письма и разделяются между собой разделителем из заголовка Boundary.

  Описание: Каждое полученное за время отсутствия сообщение приходит отдельным пакетом в том порядке, в каком они поступали на сервер.

• Пакет: Удаление сохраненного сообщения

  Имя пакета: MRIM_CS_OFFLINE_MESSAGE_DEL
  Тип пакета: cs
  Параметры:

  UIDL ## uidl

  Описание: На каждый полученный MRIM_CS_OFFLINE_MESSAGE_ACK клиент обязан отправить MRIM_CS_OFFLINE_MESSAGE_DEL с тем же uidl, подтверждающий получение данного сообщения. Сообщение стирается на сервере только при получении этой команды.

• Пакет: Авторизация пользователя на добавление в контакт-лист

  Имя пакета: MRIM_CS_AUTHORIZE
  Тип пакета: cs
  Параметры:

  LPS ## user ## email пользователя

  Описание: Отправляется, чтобы разрешить user добавление пользователя в контакт-лист и наблюдение за его статусом.

• Пакет: Информация об авторизации

  Имя пакета: MRIM_CS_AUTHORIZE_ACK
  Тип пакета: sc
  Параметры:

  LPS ## user ## email авторизовавшего пользователя

  Описание: Отсылается сервером после получением им MRIM_CS_AUTHORIZE от user тому, кого user авторизовал.

• Пакет: Изменение статуса

  Имя пакета: MRIM_CS_CHANGE_STATUS
  Тип пакета: cs
  Параметры:

  UL ## status ## возможные значения совпадают с MRIM_CS_USER_STATUS, но не могут посылаться статусы STATUS_UNDETERMINATED и STATUS_OFFLINE

• Пакет: Требование ключа для web-авторизации

  Имя пакета: MRIM_CS_GET_MPOP_SESSION
  Тип пакета: cs
  Описание: Пользователь агента может заходить в почтовый ящик Mail.Ru без дополнительной авторизации и не передавая свой пароль в GET-запросе, для этого используется механизм ключей.

• Пакет: Ключ для web-авторизации

  Имя пакета: MRIM_CS_GET_MPOP_SESSION_ACK
  Тип пакета: sc
  Параметры:

  UL ## status ## успешность операции (1 - ключ получен, 0 - произошла ошибка)
  LPS ## session ## сам ключ

  Описание: Для входа в ящик можно использовать URL win.mail.ru/cgi-bin/auth?Login=email&agent=ключ.

• Пакет: Поиск контакта

  Имя пакета: MRIM_CS_WP_REQUEST
  Тип пакета: cs
  Параметры:

  UL ## field ## параметр поиска ##

  MRIM_CS_WP_REQUEST_PARAM_USER ## логин (без домена), обязан комбинироваться с доменом
  MRIM_CS_WP_REQUEST_PARAM_DOMAIN ## почтовый домен
  MRIM_CS_WP_REQUEST_PARAM_NICKNAME ## ник
  MRIM_CS_WP_REQUEST_PARAM_FIRSTNAME ## имя
  MRIM_CS_WP_REQUEST_PARAM_LASTNAME ## фамилия, * в конце ника/имени/фамилии указывает на возможность любого продолжения имени
  MRIM_CS_WP_REQUEST_PARAM_SEX ## пол. 1 - мужской, 2 - женский
  MRIM_CS_WP_REQUEST_PARAM_DATE1 ## минимальный возраст (в годах)
  MRIM_CS_WP_REQUEST_PARAM_DATE2 ## максимальный возраст (в годах)
  MRIM_CS_WP_REQUEST_PARAM_CITY_ID ## ID региона проживания
  MRIM_CS_WP_REQUEST_PARAM_ZODIAC ## Знак зодиака (Овен - 1, ..., Рыбы - 12)
  MRIM_CS_WP_REQUEST_PARAM_BIRTHDAY_MONTH ## Месяц рождения (Январь - 1, ..., Декабрь - 12)
  MRIM_CS_WP_REQUEST_PARAM_BIRTHDAY_DAY ## День рождения (обязан комбинироваться с месяцем рождения)
  MRIM_CS_WP_REQUEST_PARAM_COUNTRY_ID ## ID страны проживания
  MRIM_CS_WP_REQUEST_PARAM_ONLINE ## ищем ли мы только подключенных в данный момент пользователей (1)

  LPS ## value все параметры в строковом формате, включая числа

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

• Пакет: Найденные пользователи

  Имя пакета: MRIM_CS_ANKETA_INFO
  Тип пакета: cs
  Параметры:

  UL ## status ## успешность запроса ##

  MRIM_ANKETA_INFO_STATUS_OK ## поиск успешно завершен
  MRIM_ANKETA_INFO_STATUS_NOUSER ## не найдено ни одной подходящей записи
  MRIM_ANKETA_INFO_STATUS_RATELIMERR ## слишком много запросов, поиск временно запрещен

  UL ## fields_num ## количество полей в анкете каждого пользователя
  UL ## max_rows ## текущее ограничение на количество результатов поиска (может быть больше, чем количество строк в данном ответе)
  UL ## server_time ## текущее время на сервере (должно использоваться для вычисления возраста). Формат времени: Количество секунд с 00:00:00 1 января 1970 года.
  LPS, LPS, ... ## fields ## названия полей текущей анкеты (всего fields_num штук)
  LPS, LPS, ... ## values ## значения полей анкеты для каждого найденного по запросу пользователя в том же порядке, что в списке полей, по fields_num штук на каждого

  Описание: Результат поиска контактов. Возвращает анкеты найденных пользователей (их адреса являются полями анкеты).

• Пакет: Количество писем в почтовом ящике

  Имя пакета: MRIM_CS_MAILBOX_STATUS
  Тип пакета: sc
  Параметры:

  UL ## status ## количество непрочитанных писем

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

• Пакет: Контакт-лист

  Имя пакета: MRIM_CS_CONTACT_LIST2
  Тип пакета: sc
  Параметры:

  UL ## status ## результат запроса контакт-листа

  GET_CONTACTS_OK ## поиск выполнен успешно
  GET_CONTACTS_ERROR ## найденный контакт-лист некорректен
  GET_CONTACTS_INTERR ## произошла внутренняя ошибка

  UL ## groups_number ## количество групп в контакт-листе
  LPS ## group_mask ## маска-описание группы, состоит из символов 's' (LPS),'u' (UL),'z' (строка оканчивающаяся бинарным нулем, в данный момент не используется), сейчас "us" - флаги и название, при расширении описания старые поля сохранят свое расположение
  LPS ## contacts_mask ## маска-описание пользователя (синтаксис такой же как и у group_mask), сейчас uussuu (флаги, группа, адрес, ник, серверные флаги, текущий статус в сети)
  ## groups ## группы (всего groups_number штук)
  ## contacts ## контакты

  Описание: Контакт-лист пользователя хранится на сервере. Клиент может хранить локальную копию контакт-листа, но серверная должна иметь приоритет. Флаги контакта имеют тот же смысл, что в MRIM_CS_ADD_CONTACT, статус - тот же смысл, что в MRIM_CS_USER_STATUS. Серверный флаг в данный момент определён один - CONTACT_INTFLAG_NOT_AUTHORIZED означает, что контакт еще не авторизовал пользователя и находится в группе "Жду авторизации". Если маска контакта или группы содержит больше символов, чем необходимо, клиент должен прочитать значения этих полей и проигнорировать их.

• Пакет: Авторизация

  Имя пакета: MRIM_CS_LOGIN2
  Тип пакета: cs
  Параметры:

  LPS ## login ## email авторизующегося пользователя
  LPS ## password ## пароль
  UL ## status ## статус (см. MRIM_CS_CHANGE_STATUS)
  LPS ## user_agent ## текстовое описание клиента пользователя, например "Mail.Ru Miranda Plugin v 1.0"