XIMSS Протокол

В Сервере CommuniGate Pro реализован протокол с Интерфейсом XML для Сообщений, Расписаний и Сигналов (XIMSS протокол).

Интерфейс реализован в модуле XIMSS и поддерживается в сетях TCP/IP.

В примерах сессий протокола маркером S: помечаются данные, отправляемые Сервером, а маркером C: помечаются данные, отправляемые Клиентом.

Программные библиотеки, реализующие протокол XIMSS на стороне клиента, можно найти на сайте Клиенты XIMSS.

Протокол и Синтаксис Сообщения

Клиенты XML API могут устанавливать TCP соединения с модулем XIMSS Сервера CommuniGate Pro. После установления соединения обе стороны могут отправлять и получать сообщения.

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

Каждое сообщение должно быть сформатировано как документ XML.

Клиент, отправляя сообщение с запросом, просит Сервер совершить определённые действия и/или получить данные. Каждое сообщение запроса должно содержать атрибут id.

Когда Сервер завершает требуемую операцию, он отправляет обратно сообщение response:

• response

  Атрибуты:

  • id

    совпадает с атрибутом id сообщения запроса.

  • errorText

    этот необязательный атрибут присутствует, только если операция закончилась неуспешно. В нём содержится текст сообщения об ошибке.

  • errorNum

    этот атрибут присутствует, только если операция закончилась неуспешно. В нём содержится числовой код ошибки.

  • exeTime

    этот атрибут присутствует, если запрос содержал атрибут exeTime с ненулевым значением. В нём содержится время выполнения команды в миллисекундах, измеренное Сервером.

    Пример:

    C:<noop id="A001"/>
    S:<response id="A001"/>
    C:<myCommand id="A002" myParam="user1@example.dom" exeTime="1"/>
    S:<response id="A002" errorText="unknown command" errorNum="500" exeTime="211"/>

  Пример:

C:<noop id="A001"/>
S:<response id="A001"/>
C:<myCommand id="A002" myParam="user1@example.dom" />
S:<response id="A002" errorText="unknown command" errorNum="500" />

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

Сервер может отправлять клиенту сообщения с данными:

• при обработке сообщения запроса клиента;
  эти сообщения отправляются до отправки сообщения с ответом;
  эти сообщения содержат тот же атрибут id, что и сообщение запроса.
• при доставке в сессию клиента асинхронного события Сервера (такого, как поступление Предупреждения или Мгновенного Сообщения).
  эти сообщения не содержат в себе никакого атрибута id.

Пример:

C:<noop id="A001"/>
S:<alert gmtTime="20070502T083313" localTime="20070502T003313">Account is over quota</alert>
S:<response id="A001"/>
S:<alert gmtTime="20070502T083500" localTime="20070502T003500">Please logout, as we are shutting down.</alert>

Обратите внимание

Клиент должен отправлять какую-нибудь команду на Сервер как минимум раз в 10 минут, в противном случае Сервер закрывает соединение.

Предшествующие Входу Операции

После установления соединения с Сервером и до выполнения операции login, клиент может выполнять только перечисленные в этом разделе операции.

При установлении соединения, Сервер берёт IP Адрес, с которым соединился клиент, и выбирает Домен, которому назначен этот адрес IP.

В описанных в этом разделе операциях может явно задаваться альтернативный целевой Домен: если он найден, то он считается целевым доменом и используется в следующих операциях.

listFeatures

Эта операция указывает Серверу вернуть сообщение features, содержащее текущие доступные опции аутентификации и коммуникации.

Атрибуты:

• domain

  необязательное имя целевого Домена.

readStrings

Эта операция читает словарь (слова, теги, имена кнопок и т.п.), хранящийся в текущем Web-Интерфейсе Домена. В ответ сервер отправляет сообщение с данными словаря strings.

Атрибуты:

• skinName

  название Вида Web-Интерфейса. Если не указан, то используется Безымянный Вид Интерфейса.

• language

  язык словаря. Если атрибут отсутствует, то используется строка из настройки Язык Умолчаний для Пользователя.

• timeModified

  если этот атрибут задан, то он должен содержать значения даты и времени (по GMT). Если этот атрибут задан, то сообщение с данными strings будет иметь содержимое только при условии, что время изменения требуемого словаря новее, чем значение этого атрибута.

starttls

Эта операция указывает серверу установить безопасное соединение, используя SSL/TLS.

Атрибуты:

• domain

  необязательное имя целевого Домена.

Если сервер возвращает положительный ответ, то клиент немедленно должен начать процесс установки параметров соединения SSL/TLS.

recoverPassword

Эта операция просит сервер отправить по электронной почте пароль указанного Пользователя на адрес электронной почты, заданный Пользователем.

Атрибуты:

• domain

  необязательное имя целевого Домена.

• userName

  имя Пользователя.

Если сервер возвращает положительный ответ, то пароль Пользователя высылается по электронной почте.

Обратите внимание

Эта операция имеет некоторую задержку при отправке ответа.

signup

Эта операция предписывает Серверу создать нового Пользователя.

Атрибуты:

• domain

  необязательное имя целевого Домена.

• userName

  имя нового Пользователя.

• password

  пароль нового Пользователя.

• realName

  Настоящее Имя нового Пользователя (необязательно).

• recoverPassword

  адрес электронной почты, который используется для отправки забытого пароля (необязательно).

Если сервер возвращает положительный ответ, то Пользователь был создан.

Обратите внимание

Эта операция не производит вход на сервер от имени нового Пользователя.

Обратите внимание

Ответ на эту операцию отправляется с некоторой задержкой.

Сервер присылает следующие сообщения с данными:

features

Это синхронное сообщение с данными отправляется, когда Сервер обрабатывает операцию listFeatures.

Тело:

набор элементов XML:

• domain

  имя целевого Домена.

• sasl

  текстовым телом этого элемента является имя механизма SASL, доступного для целевого Домена.

• starttls

  если этот элемент представлен, то клиент может выполнять операцию starttls.

• nonce

  текущие данные "nonce". Эти данные "nonce" используются сервером для аутентификации методами SASL в протоколе HTTP.

• language

  в текстовом теле этого элемента содержится язык по умолчанию, выбранный для целевого Домена. Если этот элемент отсутствует, то выбирается значение языка по умолчанию (English).

• signup

  если этот элемент представлен, то клиент может выполнять операцию signup.

• connect

  если этот элемент присутствует, то он указывает на метод соединения, которым должен пользоваться клиент для входа и для запросов сессии. Он основывается на Рекомендуемых XIMSS Протоколах в Установках Домена для целевого Домена.
  Этот элемент имеет следующие атрибуты:

  • protocol

    используемый протокол http или ximss. Рекомендуемый протокол должен быть безопасным (например, https) если операция listFeatures выполнялась через безопасный протокол.

  • port

    номер используемого TCP порта. Если он не указан, то клиент должен использовать тот же порт, что использовался для отправки операции listFeatures.

Операции Входа

Клиент должен выполнить операцию login для того, чтобы аутентифицироваться и создать сессию XIMSS.

login

Атрибуты:

• domain

  необязательное имя целевого Домена.

• method

  этот атрибут задаёт использование метода SASL. Если этот атрибут отсутствует, то используется незашифрованный метод (пароль передаётся в открытом виде).

• authData

  Если используется незашифрованный метод, то этот атрибут содержит имя пользователя.
  Для всех остальных методов, это строка с данными протокола в кодировке base64.

• password

  Этот атрибут используется только для незашифрованного метода, и он содержит пароль пользователя в открытом виде.

• version

  Этот атрибут задаёт версию протокола, для которой было создано это Клиентское приложение, (например, 6.0). Если версия не указана, то Сервер предполагает использование протокола версии 5.4.

  Пример:

C:<login id="A001" authData="user1@example.dom" password="123rtu" />
S:<session id="A001" urlID="12-skejlkieuoiuoi-dnciru" userName="user1@example.dom" realName="User J. Smith"/>
S:<response id="A001"/>

Сервер присылает следующие сообщения с данными:

session

В этом сообщении содержится информация о вновь созданной сессии. Оно посылается перед отправкой положительного ответа на операцию login.

Атрибуты:

• urlID

  строка с идентификатором сессии. Эта строка с идентификатором может использоваться для доступа к данным сессии через протокол HTTP.

• userName

  полное имя аутентифицированного Пользователя (accountName@domainName).

• realName

  Настоящее Имя аутентифицированного Пользователя (этот атрибут отсутствует, если Настоящее Имя не указано в Установках Пользователя).

• version

  версия протокола, поддерживаемая Сервером (например, 6.1).

  Примеры:

C:<login id="A001" authData="user1@example2.dom" password="rrr123" />
S:<session id="A001" urlID="12-skejlkieuoiuoi-dnciru" userName="user1@example.dom" realName="User J. Smith" version="6.1.2" />
S:<response id="A001"/>

Когда указанный SASL метод предполагает отправку клиенту "приглашения", он отправляет сообщение с данными challenge, где атрибут value содержит данные "приглашения" для протокола SASL в кодировке base64.
Клиент должен ответить отправкой запроса auth с тем же самым атрибутом id, что использовался при запросе login и с атрибутом value, в котором содержатся данные ответа SASL протокола в кодировке base64.

Пример (смотрите RFC2195):

C:<login id="A001" method="CRAM-MD5" />
S:<challenge value="PDE4OTYuNjk3MTcwOTUyQHBvc3RvZmZpY2UucmVzdG9uLm1jaS5uZXQ+" />
C:<auth id="A001" value="dGltIGI5MTNhNjAyYzdlZGE3YTQ5NWI0ZTZlNzMzNGQzODkw" />
S:<session id="A001" urlID="12-skejlkieuoiuoi-dnciru" userName="user1@example.dom" realName="User J. Smith"/>
S:<response id="A001"/>

Двухфакторная Аутентификация

Если Двухфакторная Аутентификация настроена и требуется для завершения операции login, ответ session содержит словарь x2auth, который описывает доступные для Двухфакторной Аутентификации методы, так что каждый ключ словаря задаёт имя метода, а значения-словари - его параметры:

Параметры:

• address

  необязательный параметр, строка с маскированным адресом, на который будет отправлен одноразовый секрет.
  Метод может поддерживать несколько адресов, и тогда значением будет массив строк.

• icon

  необязательный параметр, который задаёт имя файла с картинкой для этого метода.

• humanTag

  необязательный параметр, который задаёт связанную с методом строку из Набора Данных Вида Интерфейса.

• humanName

  необязательный параметр, который задаёт название метода. Он используется, если параметр humanTag не задан. Когда не задан ни humanTag, ни humanName, используется имя метода (ключ словаря x2auth).

  Пример:

C:<login id="A001" authData="user1@example2.dom" password="rrr123" x2auth="1" />
S:<session id="A001" urlID="14-skejlkieuoiuoi-dnciru" userName="user1@example.dom" realName="User J. Smith" version="6.2c1">
S:<x2auth>
S: <subKey key="sms">
S:  <subKey key="address">+1555***2207</subKey>
S:  <subKey key="humanName">Send SMS to</subKey>
S: </subKey>
S: <subKey key="call">
S:  <subKey key="address">+1555***2207</subKey>
S:  <subKey key="humanTag">x2authvoiptag</subKey>
S:  <subKey key="icon">x2authvoip.png</subKey>
S: </subKey>
S: <subKey key="email">
S:  <subKey key="address">d***6@gmail.com</subKey>
S:  <subKey key="humanTag">x2authemailtag</subKey>
S: </subKey>
S: <subKey key="push">
S:  <subKey key="address">
S:   <subValue>John's iPhone</subValue>
S:   <subValue>Samsung Galaxy S6</subValue>
S:  </subKey>
S:  <subKey key="humanTag">x2authpushtag</subKey>
S:  <subKey key="icon">x2authvoip.png</subKey>
S: </subKey>
S:</x2Auth>
S:<session/>
S:<response id="A001"/>

При получении такого ответа клиент должен предоставить пользователю возможность выбрать метод проведения второго этапа аутентификации и использовать выбранный метод с командой x2AuthStart для запуска этого метода, а команду x2AuthComplete для завершения.

x2AuthStart

Эта операция начинает передачу одноразового секрета на устройство пользователя, используя выбранный метод. В случае успеха Сервер возвращает ответ x2auth.

Атрибуты:

• index

  Необязательный индекс для указания выбранного адреса, если метод поддерживает несколько.

  Тело:

  • Строка с именем выбранного метода.

x2AuthComplete

Тело:

• Необязательная строка с одноразовым секретом для завершения двухфакторной аутентификации.

В ответ на команду x2AuthStart сервер присылает следующее сообщение:

• x2auth

  Атрибуты:

  • user

    Установлен, когда для разблокировки сессии x2AuthComplete должна использоваться с одноразовым секретом, введённым пользователем. Это - поведение по умолчанию.

  • background

    Установлен, проверка одноразового секрета должна быть выполнена в фоне. В этом случае команда x2AuthComplete выполняется без параметра с секретом, только для проверки статуса.

После получения команд x2AuthStart и x2AuthComplete при выполнении второго этапа аутентификации в фоне сервер может прислать следующее асинхронное сообщение:

• x2AuthCompleted

Процесс установки TOTP для Двухфакторной Аутентификации

Если включена обязательная Двухфакторная Аутентификация пользователя, и пользователь выбрал аутентификацию на основе TOTP, то после вызова x2AuthStart сервер проверяет, был ли ранее пользователем установлен секрет TOTP.

Если секрет ранее не был установлен, то сервер вернёт ошибку "TOTP is not initialized yet". В случае получения такой ошибки, клиент должен отправить команду totpGenerateSecret, для генерации нового секрета. В ответ пользователь получит сообщение totpSecret со сгенерированным и закодированным в формате Base32 секретом и закодированным в формате Base64 изображением QR-кода для сканирования приложением для работы с одноразовыми паролями.

После сканирования QR-кода приложением для работы с одноразовыми паролями, необходимо полученный ранее от сервера секрет вместе с одноразовым паролем из приложения отправить обратно серверу командой totpSetSecret. В случае успешной проверки одноразового пароля и установки секрета, сервер вернёт пустой ответ, после чего и процесс инициализации TOTP, и процесс двухфакторной аутентификации будут считаться успешно завершёнными и станет доступен полный набор операций для работы с аккаунтом. В случае ошибки проверки одноразового пароля, сервер вернёт ответ с описанием ошибки.

totpGenerateSecret

Эта операция запрашивает генерацию секрета TOTP. В случае успеха сервер присылает следующее сообщение:

• totpSecret

  Атрибуты:

  • secret

    Сгенерированным сервером и закодированным в формате Base32 секрет TOTP.

  Тело:

  • Объект XML base64 с изображением QR-кода для сканирования приложением для работы с одноразовыми паролями.

  Пример:

C:<totpGenerateSecret id="A001" />
S:<totpSecret id="A001" secret="S426CAWTPDNE4YRPRCQBFBEBRI======">
S:<base64>
S: iVBORw0KGgoAAAANSUhEUgAAADEAAAAxAQMAAABJUtNfAAAABlBMVEX///8AAABVwtN+ AAABPU
S: lEQVR4nGNgIAD4Hx5IUP7BwMChE285iYOBgXsJ44quF0B60V4rIxC9cnN1FJDmUP1aawSU53+1a
S: tVqoHoGhmu1QGEGrkU85zImMDCwytqtadFgYGCyvOFw1gPID9n3/yBQntXO586lCwwMLNf03p/L
S: YGBgXm33jA1Is7csvXugAyj+6kIjO1A9W//H2bckgOK/vqh07wBqjFv5/G8EUP3PBSzHHYDyp2x
S: O9FsAzd/xgOfwD6C597akVwDNZTXSOeF2AKh+5tszDziA6lYrpORpAPm31uZ8A1LsdsfDwwKADJ
S: 5NZ/iAFFOFltPxGUB1zsdjQoF8tgy2GfJA9zPwy9/yOAGkHnOd4OoA+ld9XvqLA0D/rzp0xP8GK
S: Dy4el7uANIruPwkgfZzKMafuwk0l//llzu3gPIEAADVbDp+iAEAAIzZSNUAAAAASUVORK5CYII=
S:</base64>
S:<totpSecret/>
S:<response id="A001"/>

totpSetSecret

Эта операция запрашивает установку секрета TOTP для пользователя. В случае успешной установки секрета, сервер вернёт пустой ответ.

Атрибуты:

• secret

  Закодированный в формате Base32 секрет TOTP, полученный в ходе выполнения операции totpGenerateSecret.

• code

  Одноразовый пароль, полученный из приложения для работы с одноразовыми паролями, полученный после сканирования QR-кода.

Пример:

C:<totpSetSecret id="A001" secret="S426CAWTPDNE4YRPRCQBFBEBRI======" code="123456" />
S:<response id="A001"/>

Служебные Операции

Следующие операции могут использоваться для управления соединением клиент-сервер.

noop

Эта операция ничего не делает и всегда заканчивается успешно.

bye

Эта операция ничего не делает и всегда заканчивается успешно. После того, как сообщение с ответом было отправлено клиенту, Сервер закрывает соединение и уничтожает текущую сессию.

passwordModify

Эта операция изменяет Пароль Пользователя и/или адрес электронной почты, куда будет высылаться забытый пароль.

Атрибуты:

• oldPassword

  текущий пароль Пользователя. Операция проверяет этот пароль до того, как пытается изменить его.

• newPassword

  в этом необязательном атрибуте задаётся новый пароль. Для этого Пользователя должна быть разрешена операция Изменение Пароля.

• recoveryEMail

  этот необязательный атрибут указывает новый адрес электронной почты для восстановления пароля.

• name

  этот необязательный атрибут задаёт метку для "пароля приложения".

• remove

  если этот необязательный атрибут установлен в yes, будет удалён "пароль приложения" с меткой, заданной в параметре name.

listSpecPasswords

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

setSessionOption

Эта операция устанавливает значение параметра для текущей сессии.

Атрибуты:

• name

  имя параметра

• value

  значение параметра.

  Поддерживаются следующие параметры сессии:

  • reportMailboxChanges

    если значение параметра - yes, Сервер присылает сообщения с данными mailboxModified; для любого другого значения посылка таких сообщений прекращается.

  • idleTimeout

    максимальное время бездействия в сессии устанавливается в указанное количество секунд или в большее значение, если указанное значение не может быть использовано.

listUploaded

Эта операция запрашивает информацию об одном или всех файлах из "набора загруженных файлов". Сервер возвращает информацию о загруженных файлах в сообщении с данными uploadedFile (смотрите ниже).

Атрибуты:

• uploadID

  если этот необязательный параметр указан, то информация запрашивается только для файла с указанным fileID.
  Если этот параметр не указан, то информация запрашивается только всех файлов.

clearUploaded

Эта операция удаляет один или все файлы из "набора загруженных файлов".

Атрибуты:

• uploadID

  если этот необязательный параметр указан, то из "набора загруженных файлов" удаляется файл только с таким fileID.
  Если этот параметр не указан, то из "набора загруженных файлов" удаляются все файлы.

readConfigFile

Эта операция читает с Сервера конфигурационный файл. Сервер отправляет сообщение с данными configFile, содержащее данные конфигурационного файла (смотрите ниже).

Атрибуты:

• name

  имя конфигурации.

• timeModified

  если этот атрибут задан, то он должен содержать значения даты и времени (по GMT). Если этот атрибут задан, то сообщение с данными configFile имеет содержимое, только если время изменения требуемого конфигурационного файла новее, чем значение этого атрибута.

readTime

Эта операция читает текущее время Сервера. Сервер отправляет сообщение currentTime.

readStatus

Эта операция читает текущий статус Пользователя. Сервер отправляет сообщение currentStatus.

readSession

По этому запросу Сервер перепосылает сообщение с данными session (которое приходит клиенту при создании новой сессии).

listKnownValues

По этому запросу Сервер присылает сообщение knownValues. Это сообщение содержит наборы "известных значений": известные названия Часовых Поясов, имена кодировок и т.д.

skinList

Эта операция перечисляет Виды Интерфейса, доступные в текущем Домене.

Атрибуты:

• filter

  необязательный атрибут, указывающий на шаблон строки с символом звёздочка (*), используемым как символ подстановки. Возвращаются только те имена Видов Интерфейса, которые соответствуют этому шаблону. Сервер возвращает одно сообщение skinInfo для каждого найденного Вида Интерфейса.

skinFileList

С помощью этой операции можно получить список имён файлов выбранного Вида Интерфейса.

Атрибуты:

• skinName

  название Вида Web-Интерфейса. Если не указан, то используется Безымянный Вид Интерфейса.

• filter

  необязательный атрибут, указывающий на шаблон строки с символом звёздочка (*), используемым как символ подстановки. Возвращаются только те имена файлов, которые соответствуют этому шаблону. Сервер возвращает одно сообщение skinFileInfo для каждого найденного файла.

skinFileRead

Эта операция читает файл из указанного Вида Интерфейса текущего Домена.

Атрибуты:

• skinName

  название Вида Web-Интерфейса. Если не указан, то используется Безымянный Вид Интерфейса.

• fileName

  имя файла, который необходимо прочитать.

• type

  Если этот атрибут существует и его значением является binary, то данные файла возвращается в кодировке base64. Сервер возвращает сообщение skinFileData.

cliExecute

Эта операция выполняет команду CLI.

Атрибуты:

• report

  если этот атрибут присутствует и имеет значение xml, то результирующий объект будет отправлен в виде XML.

  Тело:

  • текст команды CLI

  Если команда CLI имеет результат, то сервер отправляет сообщение cliResult.

retrieveXML

Эта операция читает документ XML на удалённом сервере. У текущего Пользователя должна быть включена Услуга HTTP.

Атрибуты:

• url

  URL на документ XML (http: или https:).

• timeout

  тайм-аут выполнения операции (в секундах). Если документ получен успешно, то Сервер отправляет сообщение retrievedXML с содержимым полученного документа.

httpCall

По этому запросу Сервер посылает запрос HTTP удалённому серверу и получает ответ. У текущего Пользователя должна быть включена Услуга HTTP.
Операция использует указанный URL, словарь с параметрами запроса и максимальный тайм-аут в 30 секунд, запрашивая модуль Клиент HTTP выполнить запрос по протоколу HTTP.

Атрибуты:

• url

  URL запроса (http: или https:).

• другие атрибуты

  если указаны, то эти атрибуты используются для создания словаря запроса.

Тело:

Если указано, то используется для задания элемента body словаря запроса HTTP. Должен использоваться один из следующих форматов:

• текстовое тело

  этот текст используется в качестве тела запроса.

• один объект XML body

  текстовое значение элемента используется в качестве тела запроса.

• один объект XML base64

  текстовое значение элемента декодируется из формата base64, и полученный блок данных используется в качестве тела запроса.

• набор объектов XML field

  словарь с этими элементами используется в качестве тела запроса (обычно для передачи параметров запроса HTTP POST).
  Каждый элемент field задаёт поле формы: атрибут name задаёт имя поля в форме; значение поля задаётся телом элемента field, которое должно быть либо текстовым, либо представлением XML числа, блока данных или словаря (за подробностями обратитесь к описанию модуля Клиент HTTP). Помимо таких элементов данных body, тело запроса httpCall может содержать:

• один XML элемент supplFields

  тело элемента должно содержать один или более элементов subKey, задающих словарь с дополнительными полями запроса HTTP.

• один XML элемент urlParams

  тело элемента должно содержать один или более элементов subKey, задающих словарь с дополнительными параметрами URL запроса HTTP. По завершению транзакции, Сервер отправляет сообщение retrievedURL с результатами транзакции.

spellerList

Эта операция приводит к тому, что сервер отправляет сообщения speller, в которых содержатся имена установленных программ для проверки орфографии.

spellerCheck

Эта операция проверяет корректность написания произвольного текста. Для каждой обнаруженной ошибки, Сервер отправляет сообщение spellerReport.

Атрибуты:

• speller

  имя программы для проверки орфографии.

• mode

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

Тело:

• проверяемый текст.

getSessionData

Эта операция приводит к тому, что сервер отправляет сообщение sessionData - XML-представление словаря с дополнительными параметрами сессии или его части, имя ключа которой указано в атрибуте name.

Атрибуты:

• name

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

setSessionData

Эта операция изменяет содержимое словаря с дополнительными параметрами сессии.

Атрибуты:

• name

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

• delete

  если задан этот необязательный атрибут, то часть параметров по указанному в нйм ключу удаляется.

Тело:

XML-представление словаря с дополнительными параметрами сессии или его части, имя ключа которой указано в атрибуте name.

getLanguage

в результате этой операции сервер присылает сообщение language с именем языка, который используется для операций со скриптами и шаблонами WSSP.

setLanguage

Эта операция изменяет имя языка, который используется для операций со скриптами и шаблонами WSSP.

Атрибуты:

• language

  имя языка.

Сервер может отправлять следующие служебные сообщения с данными в любое время:

alert

Аутентифицированный Пользователь получает Предупреждение. Как только сервер отправляет Клиенту сообщение данных с Предупреждением, сообщение Предупреждения помечается как "подтверждённое".

Атрибуты:

• gmtTime

  время опубликования предупреждения (GMT).

• localTime

  время опубликования предупреждения (в выбранном часовом поясе).

• Тело:

  текст Предупреждения (в кодировке UTF-8).

bye

Сервер решил закрыть сессию (тайм-аут, действия администратора и т.д.).
Клиент должен закрыть соединение с Сервером (если оно имеется) и проинформировать пользователя.

newUploaded

Новый файл был добавлен в "набор загруженных файлов".

Атрибуты:

• uploadID

  строка, идентифицирующая этот файл в "наборе загруженных файлов".

mailboxModified

Некоторые папки Пользователя были изменены. Такие сообщения присылаются сервером, только если значение атрибута reportMailboxChanges в сессии установлено в yes.

Атрибуты:

• mailbox

  имя изменённой папки

session

Сервер присылает это сообщение в ответ на команду getSessionData.
Оно содержит XML-представление запрошенной части словаря с дополнительными параметрами сессии.

sessionDataModified

Сервер присылает это сообщение, если словарь с дополнительными параметрами сессии модифицировался извне.

Сервер может отправлять следующие сообщения с данными:

uploadedFile

Это синхронное сообщение с данными отправляется, когда Сервер отрабатывает запрос listUploaded.

Атрибуты:

• uploadID

  строка, идентифицирующая файл в "наборе загруженных файлов".

• fileName

  имя загруженного файла (может отсутствовать)

• size

  размер загруженного файла

• type

  тип загруженного файла

• subtype

  подтип загруженного файла (может отсутствовать)

• charset

  кодировка тела загруженного файла (может отсутствовать)

strings

Это синхронное сообщение с данными отправляется Сервером при обработке запроса readStrings.

Атрибуты:

• skinName

  название Вида Web-Интерфейса.

• language

  выбранный язык.

• timeModified

  дата и время изменения словаря (время GMT).

Тело:

набор из XML элементов string и strings. У каждого элемента есть атрибут name - имя (или "ключ") элемента словаря.
Элементы словаря типа строка представляются с использованием элементов string. Телом элемента string является значение элемента словаря.
Элементы словаря типа словарь представляются с использованием элементов strings. Телом элемента strings является набор XML элементов string.
Элементы словаря типа массив представляются при помощи элементов strings. Телом элемента strings является набор XML элементов string без атрибута name. Пример:
Клиент читает словарь по умолчанию (английский).

C:<readStrings id="A001" />
S:<strings id="A001" language="" >
    <string name="AppendButton">Append</string>
    <strings name="AppendModes">
      <string name="simple">Simple Mode</string>
      <string name="advanced">Advanced Mode</string>
    </strings>
    <strings name="KnownFields">
      <string>From</string>
      <string>Subject</string>
    </strings>
  </strings>
S:<response id="A001"/>

configFile

Это синхронное сообщение с данными отправляется Сервером при обработке запроса readConfigFile.

Атрибуты:

• skinName

  название Вида Web-Интерфейса.

• name

  имя конфигурации.

• timeModified

  дата и время изменения конфигурации (время GMT).

• Тело:

элемент XML типа config

currentTime

Эти сообщения отправляются, когда Сервер обрабатывает запрос readTime.

Атрибуты:

• gmtTime

  текущее Время Сервера (GMT).

• localTime

  текущее Время Сервера (в выбранном часовом поясе).

currentStatus

Эти сообщения отправляются, когда Сервер обрабатывает запрос readStatus.

• Тело:

  набор элементов XML:

  • messageStore

    Информация о Хранилище Почты Пользователя.

    Атрибуты:

    • used

      текущий объём использованного хранилища (в байтах).

    • limit

      размер Квоты Хранилища. Этот атрибут отсутствует, если ограничение для квоты не установлено.

  • fileStore

    Информация о Хранилище Файлов Пользователя.

    Атрибуты:

    • limit

      размер квоты хранилища файлов. Этот атрибут отсутствует, если ограничение для квоты не установлено.

    • fileSizeLimit

      размер квоты размера файла. Этот атрибут отсутствует, если ограничение для квоты не установлено.

    • fileLimit

      размер квоты числа всех файлов. Этот атрибут отсутствует, если ограничение для квоты не установлено.

  • PrevLogin

    Информация о предыдущем успешном входе на сервер.

    Атрибуты:

    • gmtTime

      время входа (GMT).

    • localTime

      время входа (в выбранном часовом поясе).

    • ip

      сетевой адрес, с которого вошёл пользователь.

  • LastFailedLogin

    Информация о последней неудачной попытке входа на сервер.

    Атрибуты:

    • gmtTime

      время последней неудачной попытки входа на сервер (GMT).

    • localTime

      время последней неудачной попытки входа на сервер (в выбранном часовом поясе).

    • ip

      сетевой адрес, с которого была предпринята попытка входа на сервер.

  • RulesAllowed, SignalRulesAllowed, RPOPAllowed, RSIPAllowed, PWDAllowed, PasswordRecovery, EncryptedMailboxesAllowed

    Фактически действующие Установки Пользователя. Эти элементы не имеют атрибутов и текст их тела является значением установки.

  • option

    ноль, один или несколько XML элементов. Телом элемента является строка, указывающая опцию, включённую для текущего Пользователя:

    • S/MIME

      Услуги Безопасной Почты (S/MIME Защиты) включены.

    • SMIMEActive

      Услуги Безопасной Почты (S/MIME Защиты) разблокированы.

    • SMIMEInactive

      Услуги Безопасной Почты (S/MIME Защиты) заблокированы (но Пользователь имеет Закрытый Ключ PKI).

    • WebCAL

      Услуги календаря включены.

    • WebSite

      Веб Доступ к Хранилищу Файлов по HTTP включён.

    • Signal

      Услуги Сигналов включены.

    • PBX

      Услуги УПАТС включены.

    • HTTP

      Услуги HTTP транзакций включены.

  • signalBind

    Информация о параметрах Сигнализации Реального Времени для сессии.

    Атрибуты:

    • name

      имя «идентификатора клиента» для этой сессии.

  • hiddenModules

    Список (через запятую) имён деактивированных клиентских модулей.

  • timeout

    Информация о тайм-аутах сессии.

    Атрибуты:

    • limit

      ограничение Времени Сессии в секундах

    • idle

      необязательно; тайм-аут бездействия, в секундах. Если атрибут не задан, то тайм-аут по бездействии для этой сессии отключён.

knownValues

Эти сообщения присылаются, когда Сервер обрабатывает запрос listKnownValues.

• Тело:

  набор элементов XML:

  • tzid

    атрибут name элемента указывает наименование известного Часового Пояса;

  • charset

    атрибут name элемента указывает наименование известной кодировки;

  • mailRuleAllowed

    атрибут name элемента задаёт поддерживаемые режимы Разрешённых Почтовых Правил. Каждый режим определяет, какие действия Почтовых Правил пользователю разрешается изменять; элементы сортируются так, чтобы первыми были перечислены "наиболее ограничивающие" режимы.

  • mailRuleCondition

    атрибут name элемента указывает поддерживаемое условие Почтовых Правил.

  • mailRuleAction

    атрибут name элемента указывает поддерживаемое действие Почтовых Правил; атрибут allowedSet элемента указывает задействование имени Разрешённого Почтового Правила. Пользователь может изменять Правило, содержащую эту операцию, только если в значении Установки Разрешённые Правила для Почты Пользователя установлен менее ограничивающий режим для Разрешённых Правил для Почты.

  • signalRuleAllowed, signalRuleCondition, signalRuleAction

    аналогично элементам mailRuleAllowed, mailRuleCondition, mailRuleAction, но для Правил Сигналов.

  • safeSchema

    атрибут name элемента указывает имя схемы для ссылки, безопасной в содержимом писем.

  • webAccessURL

    атрибут name элемента задаёт предпочтительный для домена URL (схема, имя хоста, порт) для доступа к web-услугам.

skinInfo

Это синхронное сообщение с данными присылается, когда Сервер обрабатывает запрос skinList.

Атрибуты:

• skinName

  название Вида Web-Интерфейса.

skinFileInfo

Это синхронное сообщение с данными отправляется, когда Сервер обрабатывает запрос skinFileList.

Атрибуты:

• skinName

  название Вида Web-Интерфейса.

• fileName

  имя файла.

• size

  размер файла в байтах.

• timeModified

  необязательный атрибут, в котором находится дата и время изменения файла (местное время).

skinFileData

Это сообщение отправляется, когда Сервер обрабатывает запрос skinFileRead.

Атрибуты:

• fileName

  имя файла.

• timeModified

  дата и время изменения файла (местное время).

• Тело:

  Либо текст с данными файла, либо элемент base64. Текстовым телом этого элемента XML являются данные файла в кодировке base64 (кодировка base64 позволяет получать двоичные данные).

cliResult

Эти сообщения отправляются, когда Сервер обрабатывает запрос cliExecute.

• Тело:

  представление XML или текст результата работы команды CLI. Пример:
  Клиент читает псевдонимы некоторого Пользователя.

C:<cliExecute id="A001">GETACCOUNTALIASES user@domain.com</cliExecute>
S:<cliResult id="A001">(alias1,alias2)</cliResult>
S:<response id="A001"/>
C:<cliExecute id="A002" report="xml">GETACCOUNTALIASES user@domain.com</cliExecute>
S:<cliResult id="A002"><subValue>alias1</subValue><subValue>alias2</subValue></cliResult>
S:<response id="A002"/>

retrievedXML

Эти сообщения отправляются, когда Сервер обрабатывает запрос retrieveXML.

Атрибуты:

• url

  URL документа.

• Тело:

  один элемент XML, в котором содержится полученный документ.

retrievedURL

Эти сообщения присылаются, когда Сервер обрабатывает запрос httpCall.

Атрибуты:

• url

  URL документа.

• другие атрибуты

  элементы словаря результатов, переданного модулем Клиент HTTP (исключая элемент body).

• Тело:

элемент body словаря результата запроса:

• элемент является строкой

  текстовое тело с этой строкой

• элемент является блоком данных

  объект XML base64, содержащий блок данных в кодировке base64

• элемент является Объектом XML

  объект XML

speller

Эти сообщения присылаются, когда Сервер обрабатывает запрос spellerList.

Атрибуты:

• speller

  имя программы для проверки орфографии, обычно - название языка или название диалекта (такое, как English-US или French-CA).

spellerReport

Эти сообщения отправляются, когда Сервер обрабатывает запрос spellerCheck и обнаруживает ошибку орфографии.

Атрибуты:

• position

  позиция неверно написанного слова в проверяемом тексте.

• size

  размер неверно написанного слова в отправленном тексте (в байтах).

Тело:

ноль, один или несколько элементов XML guess. Текст тела каждого элемента является предлагаемой заменой для неверно написанного слова.

Обратите внимание

Проверяемый текст сначала декодируется из XML, и в атрибутах указывается позиция слова и размер в результирующем декодированном тексте (который должен быть в кодировке UTF-8).

Обратите внимание

Позиция и длина указываются либо в байтах, либо в символах - в зависимости от значения атрибута mode.

Управление Папкой

Клиент может использовать следующий набор операций для работы с Папками аутентифицированного Пользователя, а также с Папками других Пользователей (указывая полное имя Папки в виде ~accountName@domainName/mailboxName).

Обратите внимание

Все имена Папок с не-ASCII символами задаются в кодировке UTF-8 (используемый в IMAP метод UTF-7 не применяется).

mailboxCreate

Эта операция создаёт новую Папку.

Атрибуты:

• mailbox

  в этом атрибуте задаётся имя новой Папки.

• mailboxClass

  этот необязательный атрибут задаёт класс Папки.

mailboxRename

Эта операция переименовывает Папку.

Атрибуты:

• mailbox

  в этом атрибуте задаётся имя существующей Папки.

• newName

  в этом атрибуте задаётся имя новой Папки.

• children

  если этот атрибут присутствует, то все "дети" Папки (вложенные Папки) также переименовываются.

mailboxRemove

Эта операция удаляет Папку.

Атрибуты:

• mailbox

  имя существующей Папки.

• children

  если этот атрибут присутствует, то удаляются также и все "дети" Папки (вложенные Папки).

mailboxList

Эта операция заставляет Сервер отправить сообщение с данными mailbox (смотрите ниже) для каждой видимой Папки (Папки, к которой аутентифицированный Пользователь имеет Права Доступа Видеть).

Атрибуты:

• filter

  в этом необязательном атрибуте задаётся строка с фильтром в формате протокола IMAP.

• mailboxClass

  если этот атрибут указан, то перечисляются только Папки указанного класса. Используйте в качестве значения пустую строку для перечисления Папок только класса "mail".

• pureFolder

  если этот атрибут существует и его значением является yes, то в результат включаются "чистые" папки; если его значением является no, то "чистые" папки не включаются.
  Подробности смотрите в описании сообщения с данными mailbox.

mailboxSubList

Эта операция заставляет Сервер отправить сообщение с данными mailboxSubscription для каждого элемента из набора подписанных папок Пользователя. Заметьте, что перечисленные в этом наборе Папки могут и не существовать.

Атрибуты:

• filter

  в этом необязательном атрибуте задаётся строка с фильтром в формате протокола IMAP.

mailboxSubUpdate

Эта операция изменяет набор подписанных папок Пользователя.

Тело:

набор элементов mailboxSubscription.

Атрибуты:

• mailbox

  имя папки в кодировке UTF-8.

• mode

  если значением этого атрибута является add, то имя mailbox добавляется в набор подписанных Папок (за исключением случая, когда в наборе уже имеется папка с таким именем).
  в противном случае, имя mailbox удаляется из набора подписанных папок.

mailboxAliasList

Эта операция заставляет Сервер отправить сообщение с данными mailboxAlias (смотрите ниже) для каждого Псевдонима Папки текущего Пользователя.

mailboxAliasUpdate

Эта операция изменяет набор Псевдонимов Папок Пользователя.

Тело:

набор элементов mailboxAlias.

Атрибуты:

• name

  Имя Псевдонима Папки в кодировке UTF-8.

• mode

  если значением этого атрибута является add, то имя Псевдоним name добавляется в набор Псевдонимов Папки. Если в наборе уже имеется Псевдоним с таким именем, то он замещается.
  в противном случае, Псевдоним name удаляется из набора Псевдонимов Папки.

Тело:

• строка: имя требуемой Папки в кодировке UTF-8.

mailboxRightsGet

Эта операция заставляет Сервер отправить сообщение с данными mailboxRights (смотрите ниже) с правами доступа к указанной Папке.

Атрибуты:

• mailbox

  имя существующей Папки.

mailboxACLList

Эта операция заставляет Сервер отправить сообщение с данными mailboxACL с данными из Списка Прав Доступа к Папке.

Атрибуты:

• mailbox

  имя существующей Папки.

mailboxACLUpdate

Эта операция изменяет Список Прав Доступа к Папке для указанной Папки.

Атрибуты:

• mailbox

  имя существующей Папки.

• Тело:

Набор элементов XML aclElem:

Атрибуты:

• pattern

  "имя" элемента ACL. Оно может быть именем Пользователя, именем с префиксом "+" или "-" и т.д. Дополнительную информацию смотрите в разделе Список Прав Доступа к Папке.

• mode

  если этот необязательный атрибут имеет значение add, то указанные права добавляются к набору прав, уже заданных для этого элемента ACL. Если элемент ACL не существует, то он будет создан.
  если этот необязательный атрибут имеет значение sub, то указанные права убираются из набора прав, заданных для этого элемента ACL.
  если этот необязательный атрибут имеет значение clear, то этот элемент ACL удаляется.
  если этот необязательный атрибут имеет любое другое значение или этот атрибут отсутствует, то указанные права замещают набор прав, уже заданный для этого элемента ACL. Если элемент ACL не существует, то он будет создан.

  Тело:

  • строка; каждый символ определяет Права Доступа к Папке.

Сервер присылает следующие сообщения с данными:

mailbox

Эти синхронные сообщения с данными отправляются, когда Сервер обрабатывает запрос mailboxList.

Атрибуты:

• mailbox

  имя Папки в кодировке UTF-8.

• UIDVALIDITY, MESSAGES, UIDNEXT, UNSEEN, OLDEST, CLASS, MEDIA, UNSEENMEDIA

  стандартные и расширенные атрибуты IMAP для Папок

• SIZE

  размер Папки (внутренний, аналогично INTERNALSIZE для IMAP).

• pureFolder

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

  Обратите внимание

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

• isFolder

  этот атрибут существует и имеет значение yes, если Папка является обычной папкой - то есть, может содержать сообщения и может содержать Подпапки.

• rights

  действующие права доступа к Папке. Если этот атрибут отсутствует, то доступ к Папке не ограничен.

mailboxSubscription

Эти сообщения отправляются, когда Сервер обрабатывает запрос mailboxSubList.

Атрибуты:

• mailbox

  имя Папки в кодировке UTF-8.

mailboxAlias

Эти сообщения отправляются, когда Сервер обрабатывает запрос mailboxSubList.

Атрибуты:

• name

  Имя Псевдонима Папки в кодировке UTF-8.

• Тело:

строка; имя целевой Папки в кодировке UTF-8.

mailboxRights

Это сообщение отправляется, когда Сервер обрабатывает запрос mailboxRightsGet.

Атрибуты:

• mailbox

  имя Папки.

• Тело:

строка; каждый символ определяет фактически действующие Права Доступа к Папке, предоставленные текущему пользователю.

mailboxACL

Это сообщение отправляется, когда Сервер обрабатывает запрос mailboxACLList.

Атрибуты:

• mailbox

  имя Папки.

Тело:

Набор элементов XML aclElem, один элемент для каждого элемента из Списка Прав Доступа к Папке:

Атрибуты:

• pattern

  "имя" элемента ACL. Оно может быть именем Пользователя, именем с префиксом "+" или "-" и т.д. Дополнительную информацию смотрите в разделе Список Прав Доступа к Папке.

Тело:

строка; каждый символ определяет Права Доступа к Папке, предоставленные или забранные от "имени".

Пример:

• A001: Клиент просит Сервер создать Папку типа Блокнот MyNotes.
• A002: Клиент просит Сервер переименовать папку MyNotes в SharedNotes.
• A003: Клиент просит Сервер предоставить права Видеть (Lookup) и Входить (Select) к Папке SharedNotes пользователям user1 и user2.
• A004: Клиент просит Сервер добавить права Удалить (Delete) и Добавить (Insert) для Папки SharedNotes пользователям user1 и забрать право Входить у пользователя user2.
• A005: Клиент запрашивает у Сервера данные ACL для Папки SharedNotes.

C:<mailboxCreate id="A001" mailbox="MyNotes" mailboxClass="IPF.StickyNote" />
S:<response id="A001"/>

C:<mailboxRename id="A002" mailbox="MyNotes" newName="SharedNotes" />
S:<response id="A002"/>

C:<mailboxACLUpdate id="A003" mailbox="SharedNotes">
    <aclElem pattern="user1">lr</aclElem>
    <aclElem pattern="user2">lr</aclElem>
  </mailboxACLUpdate>
S:<response id="A003"/>

C:<mailboxACLUpdate id="A004" mailbox="SharedNotes">
    <aclElem pattern="user1" mode="add">di</aclElem>
    <aclElem pattern="user2" mode="sub">r</aclElem>
  </mailboxACLUpdate>
S:<response id="A004"/>

C:<mailboxACLList id="A005" mailbox="SharedNotes"/>
S:<mailboxACL id="A005" mailbox="SharedNotes">
    <aclElem pattern="user1">lrdi</aclElem>
    <aclElem pattern="user2">l</aclElem>
  </mailboxACL>
S:<response id="A005"/>

Операции с Папкой

Клиент может использовать следующий набор операций для работы с Папками аутентифицированного Пользователя, а также с Папками других Пользователей (указывая полное имя Папки в виде ~accountName@domainName/mailboxName).

folderOpen

Эта операция открывает указанную Папку как "Представление Папки" ("Folder").
Представление Папки представляет собой Папку Сервера, в которой сообщения были отсортированы и, возможно, отфильтрованы.
Каждое представление папки имеет имя; в одной сессии не может быть двух представлений с одинаковыми именами. С другой стороны, в одной сессии могут быть открыто два различных преставления (с разными именами) для одной и той же Папки. Например, приложение может использовать одно представление для показа содержимого Папки, отсортированным по полю Дата, а в другом окне будет оно будет показывать ту же Папку, но отсортированную по полю От Кого и только с теми сообщениями, в поле Keywords которых имеется тег Business.
Когда в Папку добавляются сообщения (а также, когда сообщения изменяются или удаляются), Сервер уведомляет об этих изменениях всех клиентов, открывших какое-либо Представление этой Папки.
Для каждого представления уведомление об изменениях отправляется независимо, так что клиенту нет необходимости знать, что два представления папки фактически показывают разные виды одной и той же Папки Сервера.

Атрибуты:

• folder

  имя нового Представления папки, которое необходимо открыть. В качестве имени Представления клиент может использовать произвольную строку.

• mailbox

  имя Папки. Если этот атрибут не указан, то используется имя представления папки.

• mailboxClass

  необязательный атрибут. Если указанная Папка не существует, и указан этот необязательный атрибут, то указанная Папка будет создана.
  Если значением этого атрибута является непустая строка, то это значение используется как Класс Папки для создаваемой Папки.

• sortField

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

• sortOrder

  если этот необязательный атрибут задан и имеет значение desc, то применяется обратный порядок сортировки.

• filter

  если этот необязательный атрибут указан, то в представление папки включаются только те сообщения, которые соответствуют значению этого атрибута.

• filterField

  если этот необязательный атрибут указан, то его значение задаёт поле заголовка сообщения для сравнения с атрибутом filter. В представление папки включаются только те сообщения, у которых указанное поле существует, и значение которого соответствует значению атрибута filter.
  Если значением атрибута является FLAGS, то значение атрибута filter должно быть разделённым через запятую списком имён флагов сообщения и/или обратных имён флагов сообщения (negative names). В представление папки включаются только те сообщения, которые содержат указанный набор флагов и не содержат набор обратных флагов.
  Например, атрибут filter="Media,Unseen" укажет Серверу построить представление папки с использованием только тех сообщений, у которых установлен флаг Media и не установлен флаг Seen.
  Если значением этого атрибута является body, то в представление папки включаются только те сообщения, которые содержат в какой-либо части тела сообщения значение атрибута filter.
  Если этот атрибут отсутствует, то в представление папки включаются те сообщения, которые содержат значение атрибута filter в какой-либо части тела сообщения или в любом поле заголовка сообщения.

• hideDeleted

  Если этот атрибут содержится в запросе, режим представления «прятать стёртые» включается, если значение атрибута установлено в yes. Если этот атрибут отсутствует в запросе, режим представления «прятать стёртые» включается, если действительное значение Настройки Пользователя Режим Удаления установлено в Отмечать.
  Когда режим представления "прятать стёртые" включён, сообщение в папке удаляется из представления, как только ему проставляется флаг "Deleted". Если позже флаг "Deleted" снимается с объекта, он не появляется в представлении, но будет виден снова, если представление папки открыть заново.

• UIDValidity, UIDMin

  Если имеются эти необязательные числовые атрибуты и значение UIDValidity представления Папки равно значению атрибута запроса UIDValidity, то в представление Папки включаются только те сообщения, UID которых не меньше, чем значение UIDMin.

Тело:

тело запроса должно содержать один или более элементов <field>.
Каждое тело элемента должно содержать имя поля заголовка, получаемого для каждого сообщения.
Эти поля известны как поля просмотра.
Могут быть указаны следующие поля просмотра и sortField:

• From, To, Cc, Bcc, Reply-To, Sender, Return-Path или другое имя Email-field. Если заголовок сообщения содержит указанное Email-field, то оно разбирается. Если поле содержит "комментарий" (то есть "настоящее имя"), то оно используется. В противном случае используется разобранный адрес электронной почты.
• Date, Resent-Date. Значение даты поля конвертируется в GMT. Если элементы с такими значениями поля отправляются в сообщении folderReport, то они содержат атрибут localTime, указывающий значение поля в Часовом Поясе, выбранном для текущего пользователя.
• имя любого другого заголовка (Subject, X-Mailer и т.п.). Используется декодированное из MIME значение этого поля.
• E-From, E-To, или другое имя E-поле-Email. Если заголовок сообщения содержит указанное поле-Email, то оно разбирается, и используется разобранный адрес электронной почты.
• Pty. Значение поля X-Priority конвертируется в строки High, Low или в пустую строку.
• UID. Метаданные сообщения - UID (уникальный идентификатор) в Папке.
• ORIGUID. Метаданные сообщения - оригинальный UID (уникальный идентификатор) в Папке. Если только сообщение не является изменённой версией старого (и уже стёртого) сообщения, значение его ORIGUID атрибута равно значению атрибута UID.
• SIZE. Метаданные сообщения - "сырой" размер сообщения в Папке.
• INTERNALDATE. Метаданные сообщения - его отметка времени. Используется тот же формат, что для элемента Date.
• FLAGS - используются значения атрибутов метаданных сообщения.
  Дополнительную информацию о флагах сообщения в Папке смотрите в разделе Папки.

Обратите внимание

Клиент в ответ на запрос может получить также поле RECALLUNTIL. Это отметка времени, ограничивающая дату и время доступности отзыва сообщения. При возможности отзыва сообщения оно добавляется автоматически.

Сессия может использовать несколько Представлений Папки одновременно.

Клиент должен обслуживать внутренний вид Представления папки - массив или таблицу элементов для каждого сообщения из Представления. Клиент должен держать этот вид синхронизированным с видом Сервера (реализованным в этом Представлении Папки).

При открытии Представления папки Сервер отправляет сообщение с данными folderReport, содержащее общее число сообщений в Представлении папки. Клиент использует это число для создания первоначальной таблицы внутреннего вида и заполнения её пустыми элементами.

Для отображения содержимого Папки на экране, клиент проверяет, какой элемент из таблицы внутреннего вида он должен использовать. Если некоторые из этих элементов пустые, то клиент должен запросить Сервер отправить ему информацию об этих сообщениях Представления папки, задаваемых значениями индекса (позиции) в отсортированном виде (в Представлении Папки).

В некоторых Операциях с Папкой для задания сообщений Папки, к которым применяется операция, используется набор сообщений. Сообщения могут задаваться как по их UID, так и по номеру их индекса (по их позиции в Представлении папки).

Для задания сообщений по их UID, используйте один или более элементов UID.
Каждый элемент UID может включать в себя одно сообщение, в этом случае UID сообщения указывается как тело элемента <UID>12377</UID>.
Элемент UID может включать в себя диапазон UID сообщений, задаваемых при помощи атрибутов from и till: <UID from="12377" till="12455" />. Операция применяется ко всем сообщениям Папки, UID которых не меньше, чем значение атрибута from и не больше, чем значение атрибута till. Пожалуйста, помните, что сообщения в Представлении папки не обязательно отсортированы по их UID (за исключением случая использования атрибута sortField="UID" в операции folderOpen).

Для задания сообщения по индексу, используйте один или более элементов index.
Каждый элемент index может включать в себя одно сообщение, в этом случае индекс сообщения указывается как тело элемента <index>14</index>.
Элемент index может включать в себя диапазон индексов сообщений, задаваемых при помощи атрибутов from и till: <index from="12" till="10000" />. Операция применяется ко всем сообщениям Представления папки, позиция (индекс) которых не меньше, чем значение атрибута from и не больше, чем значение атрибута till.

Набор сообщений может включать в себя один или более элементов UID или же один или более элементов index, но он не может включать в себя одновременно элементы UID и index.

folderBrowse

Эта операция заставляет Сервер отправить сообщения данных для указанного интервала индексов (позиций) в открытом Представлении папки.

Атрибуты:

• folder

  имя Представления папки.

Тело:

набор сообщений (смотрите выше). Сервер отправляет сообщение данных folderReport для каждого индекса из указанного диапазона. Атрибуты сообщения данных указывают индекс (позицию) сообщения в Представлении папке и UID сообщения.
Тело сообщения данных folderReport содержит значения viewer fields.

Для синхронизации клиента с сервером используется модель "по требованию". При добавлении, изменении или удалении сообщения из Представления папки, клиент получает асинхронное сообщение данных folderReport со значением атрибута mode, установленного в значение notify (сообщение "notify-mode").

Новые добавленные сообщения не становятся видимыми в логическом Представлении папки, а удалённые сообщения не удаляются из логического Представления папки. Запросы на получение данных из удалённых сообщений не возвращают объекты данных или же возвращают пустые объекты данных.

Когда клиентские приложения готово обновить свой "внутренний вид", оно должно использовать операцию folderSync:

folderSync

Эта операция предписывает Серверу отправить клиенту все ожидающие изменения Представления папки.

Атрибуты:

• folder

  имя Представления папки.

• limit

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

Сервер отправляет сообщения с данными folderReport с атрибутом mode, установленным в значение removed, added, updated или attrsUpdated.

После того, как Сервер отправляет "уведомительные" сообщения Клиенту, Сервер может не отправлять дальнейшие "уведомительные" сообщения для этого Представления папки до тех пор, пока клиент не выполнит операцию folderSync для этого Представления папки.

Если указан атрибут limit и запрошенное количество сообщений было прислано сервером, Сервер завершает операцию folderSync, но ожидает от клиента нового запроса folderSync для этого Представления папки, прежде чем он пришлёт новые сообщения в режиме "notify-mode" для этого представления.

Клиент может отправлять запросы на Сервер, запрашивая проведение определённых операций изменения (таких, как удаление сообщения), но он должен обновлять свой внутренний вид только когда Сервер отправляет сообщение данных folderReport, информирующее клиента о фактических изменениях в Представлении папки.

Обратите внимание

В отличие от UID, индекс сообщения в Представлении папки может изменяться каждый раз при проведении операции folderSync. До того, как вы начнёте любую операцию с использованием набора сообщений, базирующегося на индексах, убедитесь, что вы корректно изменили внутренний вид в соответствии со всеми сообщениями данных folderReport, сгенерированными предыдущей операцией folderSync.

Обратите внимание

Если сообщение было удалено или, наоборот, добавлено в Папку, то Сервер отправляет только сообщения данных folderReport с атрибутом mode="notify". Серверная сторона "вида" изменённого Представления Папки (логического Представления папки) не изменяется и можно безопасно использовать основывающиеся на индексах наборы сообщений для начала операции с Представлением папки.

folderSearch

Эта операция ищет сообщения в открытом Представлении папки.

Атрибуты:

• folder

  имя Представления папки.

• filter

  строка поиска как в протоколе IMAP для команды SEARCH.

• limit

  необязательно; максимальное количество возвращаемых сообщений.

• timeout

  необязательно; максимальное время выполнения операции в секундах. Не более 5.

Тело:

набор сообщений (смотрите выше).

Сервер отправляет сообщение данных folderSearchResult с элементами UID или index для сообщений, удовлетворяющих критериям поиска. Если поиск не завершился из-за превышения лимита времени или числа найденных сообщений, то ответ будет содержать атрибут next со значением UID или index, с которого продолжать следующий поиск.

Example:

C:<folderSearch id="A001" folder="INBOX" limit="5" timeout="1" filter="SINCE 1-Feb-2008 NOT FROM Smith OR SUBJECT test SUBJECT xxx">
    <UID from="0" till="1000"/>
  </folderSearch>
S:<folderSearchResult id="A001" folder="INBOX" next="480"><UID>285</UID><UID>386</UID><UID>479</UID></folderSearchResult>
S:<response id="A001"/>

mailboxSync

С помощью этой операции можно получить отчёт обо всех изменениях в папке с момента последней синхронизации.

Атрибуты:

• folder

  имя Представления папки.

• clientID

  строка, идентифицирующая клиентское приложение; для каждого такого приложения сервер поддерживает отдельную историю изменений.

• syncID

  строка, являющаяся ключом синхронизации; при первом обращении надо использовать значение "0".

• limit

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

• timeFrom

  необязательный параметр - отметка времени для самого старого сообщения в ответе.

• totalSizeLimit

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

Сервер отвечает набором синхронных сообщений mailboxSyncReport, которые содержат описания изменений с момента последней синхронизации.

messageCopy

Эта операция копирует сообщения из открытого Представления папки в целевую Папку.

Обратите внимание

Цель является Папкой, а не Представлением папки.

Атрибуты:

• folder

  имя Представления папки - источника.

• targetMailbox

  имя Папки-приёмника.

• mailboxClass

  Если Папка-приёмник не существует и указан этот необязательный атрибут, то Папка-приёмник будет создана. Если значением этого атрибута является непустая строка, то это значение используется как Класс Папки для создаваемой Папки.

• encrypt

  если этот необязательный атрибут задан со значением yes, то все сообщения копируются в зашифрованном виде с использованием S/MIME Сертификата текущего пользователя.

• decrypt

  если этот необязательный атрибут задан и имеет значение yes, а атрибут encrypt не задан, то все сообщения копируются в расшифрованном виде. Закрытый Ключ Пользователя должен быть разблокирован, иначе операция завершится с ошибкой.

• report

  Если этот атрибут задан, то он должен иметь значение uid.
  Если сообщение было успешно создано и добавлено в Папку-приёмник, то Сервер отправляет синхронное сообщение messageAdded, содержащее UID нового добавленного сообщения.

Тело:

набор сообщений (смотрите выше).

messageMove

Эта операция аналогична операции messageCopy, но если сообщение было скопировано успешно, то операция удаляет оригинальное сообщение.

Эта операция также может быть использована для реализации "шифрования сообщений": выбранные сообщения должны быть передвинуты в ту же Папку с использованием атрибутов encrypt или decrypt.

messageMark

Эта операция изменяет флаги сообщения Папки в открытом Представлении папки.

Атрибуты:

• folder

  имя Представления папки.

• flags

  этот атрибут задаёт добавляемые или удаляемые флаги сообщения Папки. Могут быть указаны несколько операций, отделённые символом запятой. Дополнительную информацию смотрите в разделе Папки.

• mode

  необязательный атрибут. Если он установлен и равен delete, то заданные флаги удаляются (флаги с обратными именами не устанавливаются).

Тело:

набор сообщений (смотрите выше).

messageRemove

Эта операция удаляет сообщения из открытого Представления папки.

Атрибуты:

• folder

  имя Представления папки.

• mode

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

  • Immediately - сообщения физически удаляются из Папки.
  • Move To Trash - сообщения передвигаются в Мусорную Корзину (её имя указывается в настройке Пользователя TrashBox). Если указанное Представление папки является Папкой Мусорной Корзины, то сообщения удаляются физически.
  • Mark - сообщения помечаются флагом Deleted.

  Если этот атрибут не указан, то используется способ, указанный в атрибуте DeleteMode Настроек Пользователя.

• Тело:

набор сообщений (смотрите выше).

folderExpunge

Эта операция удаляет все сообщения, помеченные флагом Deleted из Папки.

Обратите внимание

Она удаляет ВСЕ отмеченные этим флагом сообщения Папки, а не только сообщения, видимые в этом Представлении папки.

Атрибуты:

• folder

  имя Представления папки.

folderClose

Эта операция закрывает открытое Представления папки.

Атрибуты:

• folder

  имя Представления папки.

folderReopen

Эта операция перестраивает открытое Представление папки, повторно сканируя Папку с использованием других параметров сортировки и других фильтров.

Атрибуты:

• folder

  имя Представления папки.

• sortField, sortOrder, filter, filterField, hideDeleted, UIDValidity, UIDMin

  эти атрибуты имеют тот же смысл, что и атрибуты операции folderOpen.

Тело:

если тело запроса содержит хотя бы один элемент <field>, то такие элементы задают новый набор полей просмотра. Если не указано ни одного элемента <field>, то набор полей просмотра не изменяется.

Когда клиент использует эту команду, Сервер отправляет сообщение folderReport с атрибутом mode, установленным в значение init, уведомляя клиента о размере нового Представления папки.
Клиент должен очистить свой внутренний вид Представления папки и заново заполнить его.

Обратите внимание

Если Клиент получает сообщение folderReport с атрибутом mode, установленным в значение notify, то после отправления Клиентом команды folderReopen, Клиент должен использовать команду folderSync сразу после получения ответа на команду folderReopen.

emptyTrash

Эта операция физически удаляет все сообщения из Папки - Мусорной Корзины (если она задана).

emptyMailbox

Эта операция физически удаляет все сообщения из указанной Папки.

Атрибуты:

• mailbox

  имя Папки.

• duration

  время (в формате "разницы времени") между текущим временем и внутренней отметкой времени самого нового сообщения, которое будет оставлено в папке. Укажите 0, чтобы удалить все сообщения.

Сервер присылает следующие сообщения с данными:

folderReport

Эти сообщения отправляются синхронно, когда Представление папки открывается или переоткрывается, а также когда клиент отправляет запросы folderBrowse или folderSync.
Эти сообщения отправляются асинхронно, когда статус Представления папки изменяется (сообщения добавляются, изменяются или удаляются), в этом случае атрибут mode устанавливается в notify.

Атрибуты:

• folder

  имя Представления папки.

• mode

  в этом необязательном атрибуте задаётся тип уведомления.

  • Если значением атрибута является init, то атрибут messages указывает общее число сообщений в Представлении папки, а атрибут unseen указывает общее число непрочитанных сообщений (сообщений без флага Seen) в Представлении папки.
    Это асинхронное сообщение данных отправляется, когда Представление папки открывается или переоткрывается.
  • Если значением атрибута является notify, то некоторые сообщения Папки были добавлены, изменены или удалены.
    Это сообщение с данными отправляется асинхронно.
    Ожидается, что в ответ клиент направит запрос folderSync для этого Представления папки.
  • Если значением атрибута является removed, то атрибуты index и UID указывают на сообщение, удаляемое из Представления папки.
    Это сообщение c данными отправляется в ответ на запрос folderSync.
    Клиент должен немедленно изменить свой внутренний вид: для всех сообщений со значениями индекса большими, чем указано в значении атрибута index, значение индекса уменьшается на 1.
  • Если значением атрибута является added, то атрибуты index и UID, задающие сообщение, добавляются в Представление папки.
    Это сообщение c данными отправляется в ответ на запрос folderSync.
    Клиент должен немедленно изменить свой внутренний вид: для всех сообщений со значениями индекса большими либо равными, чем указано в значении атрибута index, значение индекса увеличивается на 1.
  • Если значением атрибута является updated или attrsUpdated, или атрибут отсутствует, то атрибуты index и UID задают сообщение Папки и в теле содержатся значения полей просмотра сообщения.

  Этот атрибут установлен в значение error, когда Серверу не удалось выполнить запрос folderBrowse и извлечь данные сообщения (например, когда сообщение было уже удалено на сервере, но не было удалено из представления, поскольку запрос folderSync не был ещё передан на сервер.)

• index

  индекс сообщения в этом Представлении папки.
  Этот атрибут не присутствует, когда значением атрибута mode является init.

• UID

  идентификатор сообщения (уникальный ID).
  Этот атрибут не присутствует, когда значением атрибута mode является removed, updated, attrsUpdated или added.

• messages

  общее число сообщений в этом Представлении папки.
  Этот атрибут не присутствует, когда значением атрибута mode является init, removed, или added.

• unseen

  общее число новых (без флага Seen) сообщений в этом Представлении папки.
  Этот атрибут присутствует, когда значением атрибута mode является init, removed, updated, attrsUpdated или added.

• rights

  действующие права доступа для Представления папки.
  Этот атрибут присутствует, когда значением атрибута mode является init. Если этот атрибут отсутствует, то доступ к Представлению папки не ограничен.

• UIDValidity, UIDNext

  значение атрибутов UIDValidity и UIDNext Папки.
  Эти атрибуты присутствуют, когда значением атрибута mode является init.

• Тело:

Тело присутствует, когда атрибут mode не задан (в ответ на folderBrowse) или значением атрибута mode является updated, attrsUpdated или added (в ответ на folderSync).
Оно содержит набор элементов XML со значениями полей просмотра.

Пример 1:

• A001: Клиент просит Сервер открыть Папку INBOX как Представление папки "INBOX" и отсортировать её по полю INTERNALDATE (которое является не фактическим полем сообщения, а элементом метаданных сообщения, указывающим время поступления сообщения в Папку). Клиент информирует Сервер, что ему необходимо получить поля FLAGS, From и Subject сообщений Папки.
• Сервер открывает Папку INBOX и сортирует её; Сервер информирует Клиента, что в Представлении папки имеется 234 сообщения.
• A002:Клиент просит Сервер отправить ему данные первых 4 сообщений, находящихся в Представлении папки и Сервер отправляет эту информацию Клиенту.
• пока Сервер обрабатывал этот запрос, в Папку было добавлено одно сообщение.
• после того, как Сервер отправил сообщение с ответом, сообщения 2 и 35 из Представления были удалены.
• A003: Клиент снова просит Сервер отправить ему данные первых 4 сообщений, находящихся в отсортированном Представлении папки.
• A004: Клиент просит Сервер прислать ему информацию обо всех изменениях в Представлении папки.
• Сервер информирует Клиента о том, что сообщение с номером 35 было удалено. Клиент должен удалить элемент номер 35 из своей таблицы внутреннего вида и, если необходимо, обновить информацию на экране. Общее число сообщений в Представлении папки изменяется на 233.
• Сервер информирует Клиента о том, что сообщение с номером 2 было удалено. Клиент должен удалить элемент номер 2 из своей таблицы внутреннего вида. Сообщение номер 3 становится сообщением номер 2, сообщение номер 4 становится сообщением номер 3 и т.д.
• Сервер добавляет новое сообщение в Представление папки и информирует Клиента о том, что он вставил это сообщение как сообщение номер 1. Клиент должен обновить свою таблицу внутреннего вида, вставив в неё новый элемент как элемент номер 1. Элемент номер 1 становится сообщением номер 2, элемент номер 2 становится элементом номер 3 и т.д.
• A005: Клиент снова просит Сервер отправить ему данные первых 4 сообщений, находящихся в Представлении папки.

C:<folderOpen id="A001" folder="INBOX" mailbox="INBOX" sortField="INTERNALDATE" sortOrder="asc">
   <field>FLAGS</field><field>From</field><field>Subject</field>
  </folderOpen>
S:<folderReport id="A001" folder="INBOX" mode="init" messages="234" unseen="12" />
S:<response id="A001"/>

C:<folderBrowse id="A002" folder="INBOX"><index from="0" till="3" /></folderBrowse>
S:<folderReport id="A002" folder="INBOX" index="0" UID="123">
    <FLAGS>Seen,Deleted</FLAGS><From>John H. Smith</From>
    <Subject>Hello - just a test</Subject>
  </folderReport>
S:<folderReport id="A002" folder="INBOX" index="1" UID="543">
    <FLAGS>Seen,Answered,Recall</FLAGS><From>Jim Spammer</From>
    <Subject>This is the best offer!</Subject>
  </folderReport>
S:<folderReport id="A002" folder="INBOX" index="2" UID="343">
    <FLAGS>Seen,Media</FLAGS><From>user@example.com</From>
    <Subject>Meeting reminder</Subject>
  </folderReport>
S:<folderReport folder="INBOX" mode="notify" />
S:<folderReport id="A002" folder="INBOX" index="3" UID="512">
    <FLAGS>Seen,Flagged</FLAGS><From>Admin@hq.example.com</From>
    <Subject>Shutdown @ 4:45AM</Subject>
  </folderReport>
S:<response id="A002" />

S:<folderReport folder="INBOX" mode="notify" />

C:<folderBrowse id="A003" folder="INBOX"><index from="0" till="3" /></folderBrowse>
S:<folderReport id="A003" folder="INBOX" index="0" UID="123">
    <FLAGS>Seen,Deleted</FLAGS><From>John H. Smith</From>
    <Subject>Hello - just a test</Subject>
  </folderReport>
S:<folderReport id="A003" folder="INBOX" index="1" UID="543">
    <FLAGS>Seen,Answered,Recall</FLAGS><From>Jim Spammer</From>
    <Subject>This is the best offer!</Subject>
  </folderReport>
S:<folderReport id="A003" folder="INBOX" index="2" UID="343">
    <FLAGS>Seen,Media</FLAGS><From></From>
    <Subject></Subject>
  </folderReport>
S:<folderReport id="A003" folder="INBOX" index="3" UID="512">
    <FLAGS>Seen,Flagged</FLAGS><From>Admin@hq.example.com</From>
    <Subject>Shutdown @ 4:45AM</Subject>
  </folderReport>
S:<response id="A003" />

C:<folderSync id="A004" folder="INBOX" />
S:<folderReport id="A004" folder="INBOX" index="35" UID="117" mode="deleted" messages="233" unseen="11" />
S:<folderReport id="A004" folder="INBOX" index="2" UID="343" mode="deleted" messages="232" unseen="11" />
S:<folderReport id="A004" folder="INBOX" index="1" UID="976" mode="added" messages="233" unseen="12" >
    <FLAGS>Recent</FLAGS><From>CGatePro Discussions</From>
    <Subject>[CGP] Re: Session Timer?</Subject>
  </folderReport>
S:<response id="A004" />

C:<folderBrowse id="A005" folder="INBOX"><index from="0" till="3" /></folderBrowse>
S:<folderReport id="A005" folder="INBOX" index="0" UID="123">
    <FLAGS>Seen,Deleted</FLAGS><From>John H. Smith</From>
    <Subject>Hello - just a test</Subject>
  </folderReport>
S:<folderReport id="A005" folder="INBOX" index="1" UID="976">
    <FLAGS>Recent</FLAGS><From>CGatePro Discussions</From>
    <Subject>[CGP] Re: Session Timer?</Subject>
  </folderReport>
S:<folderReport id="A005" folder="INBOX" index="2" UID="543">
    <FLAGS>Seen,Answered</FLAGS><From>Jim Spammer</From>
    <Subject>This is the best offer!</Subject>
  </folderReport>
S:<folderReport id="A005" folder="INBOX" index="3" UID="512">
    <FLAGS>Seen,Flagged</FLAGS><From>Admin@hq.example.com</From>
    <Subject>Shutdown @ 4:45AM</Subject>
  </folderReport>
S:<response id="A005" />

Пример 2:

• A010: Клиент просит Сервер скопировать 3 сообщения из уже открытой Папки INBOX в Папку Archive
• Папка Archive открыта и Сервер отправляет Клиенту сообщение уведомления

C:<messageCopy id="A010" folder="INBOX" targetMailbox="Archive">
    <UID>512</UID><UID>123</UID><UID>976</UID>
  </messageCopy>
S:<folderReport folder="Archive" mode="notify" />
S:<response id="A010"/>

Пример 3:

• A020: Клиент просит Сервер отметить 3 сообщения (UID 512, 123 и 976) флагом Deleted.
• Сервер устанавливает эти флаги и отправляет Клиенту сообщение уведомления.
• A021: Клиент просит Сервер прислать ему информацию обо всех изменениях в Папке.
• Сервер отправляет изменённую информацию для сообщения с UID 512 и сообщения с UID 976. У сообщения с UID 123 флаг Deleted уже установлен, так что запрос не изменяет это сообщение и Сервер не отправляет информацию для этого сообщения.
• A022: Клиент просит Сервер сжать Папку (удалить сообщения, помеченные как Deleted).
• Сервер удаляет сообщения с UID 512, 123 и 976, а также сообщения с UID 446 и 756, у которых, как оказалось, флаг Deleted тоже был установлен. Сервер отправляет Клиенту сообщение уведомления.
• A023: Клиент просит Сервер прислать ему информацию обо всех изменениях в Папке.
• Сервер отправляет сообщения данных, информируя клиента, что он удалил сообщения с UID 512, 123, 976, 446 и 756 из отсортированного Представления Папки.
• A024: Клиент закрывает Папку INBOX.

C:<messageMark id="A020" folder="INBOX" flags="Deleted">
    <UID>512</UID><UID>123</UID><UID>976</UID>
  </messageMark>
S:<folderReport folder="INBOX" mode="notify" />
S:<response id="A020"/>

C:<folderSync id="A021" folder="INBOX" />
S:<folderReport id="A021" folder="INBOX" index="1" UID="976" mode="updated" unseen="12" >
    <FLAGS>Recent,Deleted</FLAGS><From>CGatePro Discussions</From>
    <Subject>[CGP] Re: Session Timer?</Subject>
  </folderReport>
S:<folderReport id="A021" folder="INBOX" index="3" UID="512" mode="updated" unseen="12" >
    <FLAGS>Seen,Deleted,Flagged</FLAGS><From>Admin@hq.example.com</From>
    <Subject>Shutdown @ 4:45AM</Subject>
  </folderReport>
S:<response id="A021"/>

C:<folderExpunge id="A022" folder="INBOX" />
S:<folderReport folder="INBOX" mode="notify" />
S:<response id="A022"/>

C:<folderSync id="A023" folder="INBOX" />
S:<folderReport id="A023" folder="INBOX" index="0" UID="123" mode="deleted" messages="232" unseen="12" />
S:<folderReport id="A023" folder="INBOX" index="0" UID="976" mode="deleted" messages="231" unseen="11" />
S:<folderReport id="A023" folder="INBOX" index="29" UID="446" mode="deleted" messages="230" unseen="11" />
S:<folderReport id="A023" folder="INBOX" index="123" UID="756" mode="deleted" messages="229" unseen="11" />
S:<folderReport id="A023" folder="INBOX" index="1" UID="512" mode="deleted" messages="228" unseen="11" />
S:<response id="A023"/>

C:<closeMailbox id="A024" folder="INBOX" />
S:<response id="A024"/>

mailboxSyncReport

Эти синхронные сообщения направляются сервером в ответ на команду mailboxSync.

Атрибуты:

• folder

  имя Представления папки.

• mode

  этот атрибут указывает тип записи в ответе.

  • если значение атрибута равно info, то наличие атрибута hasMore указывает на возможность повторного применения команды, чтобы получить дополнительные сообщения об изменениях, а атрибут syncID содержит значение ключа синхронизации, который надо использовать в следующем запросе.
  • Остальные записи содержат атрибут origUID, который указывает на добавленное, модифицированное или удалённое сообщение.
    В них атрибут mode указывает на тип изменения:
    removed для сообщений, что были удалены с момента последней синхронизации;
    flagsUpdated или attrUpdated для сообщение с изменёнными флагами или атрибутами;
    added или updated для новых сообщений и сообщений с изменённым содержимым;

Тело:

Тело присутствует, когда значение атрибутаmode не равно deleted. В таком случае оно собержит набор элементов со значениями полей просмотра.
Когда значение атрибута mode равно added или updated тело также содержит представление самого сообщения.

Операции с Сообщениями

Для получения Сообщений из Папок клиент может использовать следующий набор операций.

folderRead

Эта операция запрашивает у Сервера Сообщение или его часть. Оно отправляется клиенту как сообщение с данными folderMessage.

Атрибуты:

• folder

  имя Представления папки.

• UID

  UID сообщения.

• partID

  в этом необязательном атрибуте задаётся часть сообщения, которую необходимо прочитать. Если он не указан, то читается всё сообщение.

• mode

  если этот необязательный атрибут установлен в replyFrom или replyAll, то атрибут partID должен либо отсутствовать, либо указывать элемент подчасти EMail. Телом сообщения ответа folderMessage является элемент EMail с подготовленным шаблоном ответа на письмо электронной почты.
  Если этот необязательный атрибут установлен в forward, то атрибут partID должен либо отсутствовать, либо указывать элемент подчасти EMail. Телом сообщения ответа folderMessage является элемент EMail с подготовленным шаблоном переадресованного письма.
  Если используются варианты replyFromHTML, replyAllHTML или forwardHTML, то для создания шаблона нового письма используется HTML-часть оригинального письма.
  Если используются варианты html или htmlForce, тела MIME-частей в формате text/xml будут дополнительно обработаны для корректного и безопасного отображения в браузере. Дополнительно, при указании режима htmlForce, части в формате text/plain будут также преобразованы в HTML.

• totalSizeLimit

  максимальный общий размер всех возвращаемых частей сообщений.

• x509

  если этот необязательный атрибут установлен в base64, части x509 прочитанных сообщений (цифровые подписи) будут содержать данные сертификатов в формате base64.

messageAppend

Эта операция предписывает серверу сформировать Сообщение и добавить его в открытое представление папки или в произвольную Папку. Также эта операция позволяет формировать отложенные сообщения.

Атрибуты:

• folder

  имя целевого Представления папки. Если оно указано, то атрибут targetMailbox игнорируется. Для отложенных сообщений должна быть указана специальная папка Outgoing.

• targetMailbox

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

• mailboxClass

  этот необязательный атрибут может быть указан, если указан атрибут targetMailbox.
  Если Папка-приёмник не существует и этот атрибут указан, то Папка-приёмник будет создана. Если значением этого атрибута является непустая строка, то это значение используется как Класс Папки для создаваемой Папки.

• flags

  этот необязательный атрибут задаёт флаги, которые создаваемое сообщение будет иметь в Папке. Могут быть указаны несколько флагов, разделённые символом запятой. Дополнительную информацию смотрите в разделе Папки.

• internalDate

  в этом необязательном атрибуте задаётся "внутренняя отметка о времени" для создаваемого сообщения. Если этот параметр не указан, то используется текущее время.

• replacesUID

  этот необязательный атрибут может быть указан, если задан атрибут folder.
  Если сообщение было успешно создано и добавлено в Представление папки, то сообщение с UID replacesUID удаляется из Представления папки.

• replaceMode

  этот атрибут может быть указан вместе с replacesUID.
  если значение атрибута - checkOld, а в Папке не содержится сообщения с UID replacesUID, то операция заканчивается неуспешно. Эта проверка и операции добавления/удаления выполняются атомарно.
  если значение атрибута - copyOrigUID, то операция заканчивается неуспешно, если в Папке не содержится сообщения с UID replacesUID. Если же сообщение существует, то атрибут ORIGUID копируется во вновь создаваемое сообщение. Эта проверка и операции присвоения атрибутов выполняются атомарно.
  если значение атрибута - origUID, то атрибут replaceUID указывает на ORIGUID сообщения, которое надо подменить. Операция заканчивается неуспешно, если в Папке не содержится сообщения с ORIGUID, равным replacesUID. Если же сообщение существует, то атрибут ORIGUID копируется во вновь создаваемое сообщение. Эта проверка, операции добавления/стирания объектов и присвоения атрибутов выполняются атомарно.

• report

  Если этот атрибут задан, то он должен иметь значение uid.
  Если сообщение было успешно создано и добавлено в Представление папки, то Сервер отправляет синхронное сообщение messageAdded, содержащее UID нового добавленного сообщения.
  Тело: XML представление Сообщения (данные EMail).
  Если элемент EMail содержит атрибут uploadID, RFC-тело письма копируется из указанного в этом атрибуте файла из "набора загруженных файлов" сессии.
  Если элемент EMail содержит поле Date, это будет означать, что отправляемое письмо - отложенное. Оно будет отправлено в дату и время, указанные в поле Date. Вместе с полем Date должен быть указан атрибут операции messageAppend internalDate, равный Date, для корректного указания даты-времени отложенной отправки.Текстовые части XML представления сообщения должны использовать в качестве символа EOL символ Перевода Строки (0x0A).

Пример:
Клиент добавляет простое текстовое сообщение с флагами Seen и Answered в Папку "Sent". Если Папка не существует, то она создаётся.

C:<messageAppend id="A001" targetMailbox="Sent" flags="Seen,Answered" mailboxClass="" >
    <EMail>
      <From realName="Sender Name">fromName@domain</From><Subject>I'll be there!</Subject>
      <To realName="Recipient Name">toName@domain</To><X-Mailer>SuperClient v7.77</X-Mailer>
      <Date localTime="20060621T215124" timeShift="-25200">20070830T045124Z</Date>
      <Message-ID>web-40721383@domain.dom</Message-ID>
      <MIME type="text" subtype="plain">Dear Susan,&#x0A;&#x0A;I will come to your place tomorrow, thank you for the invitation!&#x0A;Mary.&#x0A;</MIME>
    </EMail>
  </messageAppend>
S:<response id="A001"/>

Эта операция добавляет в Папку следующее сообщение:

From: "Sender Name" <fromName@domain>
Subject: I'll be there!
To: "Recipient Name" <toName@domain>
X-Mailer: SuperClient v7.77
Date: Wed, 21 Jun 2006 21:51:24 -0700
Message-ID: <ximss-38150012@this.server.dom>
Content-Type: text/plain; charset="utf-8"

Dear Susan,

I will come to your place tomorrow, thank you for the invitation!
Mary.

Чтобы создать сообщения с вложенными файлами, сначала поместите файлы в "набор загруженных файлов". Затем вы можете указать их в элементах MIME, используя атрибут uploadID.
Вы можете указывать атрибуты type, subtype и (для текстовых файлов) атрибут charset. Если вы не указываете явно эти атрибуты, то они копируются из поля Content-Type HTTP запроса, который использовался при загрузке файла.

Пример:
Сначала клиент загружает 2 файла - test.gif (используя uploadID att01) и sample.pdf (используя uploadID att02). Затем клиент добавляет сообщение в Представление папки "Drafts" с флагом сообщения "Draft", заменяя существующее сообщение с UID 578.
В сообщении содержится некоторый текст в альтернативных форматах (plain и html) и загруженные файлы как вложения.
Клиент указывает Серверу отправить UID нового созданного сообщения (756).
Пока клиент добавлял новое сообщение, другой процесс добавил другие сообщения (с UID=755) в Папку "Drafts".
Затем клиент очищает "набор загруженных файлов" и повторно синхронизирует своё состояние с Представлением папки "Drafts".

C:<messageAppend id="A001" folder="Drafts" flags="Draft,Seen" replacesUID="578" report="uid" >
    <EMail>
      <From realName="Sender Name">fromName@domain</From><Subject>Text with attachments</Subject>
      <To realName="Recipient Name">toName@domain</To><X-Mailer>SuperClient v7.77</X-Mailer>
      <Date localTime="20060621T215124" timeShift="-25200">20070830T045124Z</Date>
      <Message-ID>web-40721383@domain.dom</Message-ID>
      <MIME type="multipart" subtype="mixed">
        <MIME type="multipart" subtype="alternative">
          <MIME type="text" subtype="plain">Dear Susan,&#x0A;&#x0A;I will come to your place tomorrow, thank you for the invitation!&#x0A;Mary.&#x0A;</MIME>
          <MIME type="text" subtype="html">&lt;html&gt;&lt;body&gt;&lt;i&gt;Dear Susan,&lt;/i&gt;&lt;p&gt;I will come to your place tomorrow, thank you for the invitation!&lt;p&gt;&lt;i&gt;Mary.&lt;/i&gt;</MIME>
        </MIME>
        <MIME uploadID="att01" />
        <MIME uploadID="att02" type="application" subtype="pdf" />
      </MIME>
    </EMail>
  </messageAppend>
S:<folderReport folder="Drafts" mode="notify" />
S:<messageAdded id="A001" folder="Drafts" UID="756" />
S:<response id="A001"/>
C:<clearUploaded id="A002" />
S:<response id="A002"/>
C:<folderSync id="A003" folder="Drafts"/>
S:<folderReport id="A003" folder="Drafts" index="17" UID="578" mode="removed" messages="301" unseen="0"/>
S:<folderReport id="A003" folder="Drafts" index="127" UID="755" mode="added" messages="302" unseen="1">
    <FLAGS>Recent,Drafts</FLAGS>
    <From>Other Name</From>
  </folderReport>
S:<folderReport id="A003" folder="Drafts" index="17" UID="756" mode="added" messages="303" unseen="1" >
    <FLAGS>Recent,Drafts,Seen</FLAGS>
    <From>Sender Name</From>
  </folderReport>
S:<response id="A003"/>

Эта операция добавляет в Папку следующее сообщение:

From: "Sender Name" <fromName@domain>
Subject: Text with attachments
To: "Recipient Name" <toName@domain>
X-Mailer: SuperClient v7.77
Date: Wed, 21 Jun 2006 21:51:24 -0700
Message-ID: <web-40721383@domain.dom>
Content-Type: multipart/mixed; boundary="_===38330025====my.server.domain===_"

--_===38330025====my.server.domain===_
Content-Type: multipart/alternative; boundary="_===38330025-X====my.server.domain===_"


--_===38330025-X====my.server.domain===_
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit

Dear Susan,

I will come to your place tomorrow, thank you for the invitation!
Mary.

--_===38330025-X====my.server.domain===_
Content-Type: text/html; charset="utf-8"
Content-Transfer-Encoding: 8bit

<html><body><i>Dear Susan,</i><p>I will come to your place tomorrow, thank you for the invitation!<p><i>Mary.</i>
--_===38330025-X====my.server.domain===_--

--_===38330025====my.server.domain===_
Content-Type: image/gif; name="test.gif"
Content-Disposition: attachment; filename="test.gif"
Content-Transfer-Encoding: base64

R0lGODlhCgAMAPf/AP//////zP//mf//Zv//M///AP/M///MzP/Mmf/MZv/MM//MAP+Z//+Z
zP+Zmf+ZZv+ZM/+ZAP9m//9mzP9mmf9mZv9mM/9mAP8z//8zzP8zmf8zZv8zM/8zAP8A//8A
zP8Amf8AZv8AM/8AAMz//8z/zMz/mcz/Zsz/M8z/AMzM/8zMzMzMmczMZszMM8zMAMyZ/8yZ
zMyZmcyZZsyZM8yZAMxm/8xmzMxmmcxmZsxmM8xmAMwz/8wzzMwzmcwzZswzM8wzAMwA/8wA
zMwAmcwAZswAM8wAAJn//5n/zJn/mZn/Zpn/M5n/AJnM/5nMzJnMmZnMZpnMM5nMAJmZ/5mZ
zJmZmZmZZpmZM5mZAJlm/5lmzJlmmZlmZplmM5lmAJkz/5kzzJkzmZkzZpkzM5kzAJkA/5kA
zJkAmZkAZpkAM5kAAGb//2b/zGb/mWb/Zmb/M2b/AGbM/2bMzGbMmWbMZmbMM2bMAGaZ/2aZ
zGaZmWaZZmaZM2aZAGZm/2ZmzGZmmWZmZmZmM2ZmAGYz/2YzzGYzmWYzZmYzM2YzAGYA/2YA
zGYAmWYAZmYAM2YAADP//zP/zDP/mTP/ZjP/MzP/ADPM/zPMzDPMmTPMZjPMMzPMADOZ/zOZ
zDOZmTOZZjOZMzOZADNm/zNmzDNmmTNmZjNmMzNmADMz/zMzzDMzmTMzZjMzMzMzADMA/zMA
zDMAmTMAZjMAMzMAAAD//wD/zAD/mQD/ZgD/MwD/AADM/wDMzADMmQDMZgDMMwDMAACZ/wCZ
zACZmQCZZgCZMwCZAABm/wBmzABmmQBmZgBmMwBmAAAz/wAzzAAzmQAzZgAzMwAzAAAA/wAA
zAAAmQAAZgAAM+4AAN0AALsAAKoAAIgAAHcAAFUAAEQAACIAABEAAADuAADdAAC7AACqAACI
AAB3AABVAABEAAAiAAARAAAA7gAA3QAAuwAAqgAAiAAAdwAAVQAARAAAIgAAEe7u7t3d3bu7
u6qqqoiIiHd3d1VVVURERCIiIhEREQAAACH+HUdpZkJ1aWxkZXIgMC40IGJ5IFl2ZXMgUGln
dWV0ACH5BAUEALkALAAAAAAKAAwAAAg1AHPlG0gw379cAgEoXHgw4UKFDfM9hIhQ4sSIEwFg
vCiQ4L+PIC1m/Cfx34qQGkVeBMkSZEAAOw==

--_===38330025====my.server.domain===_
Content-Type: application/pdf; name="sample.pdf"
Content-Disposition: attachment; filename="sample.pdf"
Content-Transfer-Encoding: base64

JVBERi0xLjIgDSXi48/TDQogDTggMCBvYmoNPDwNL0xlbmd0aCA5IDAgUg0vRmlsdGVyIC9G
bGF0ZURlY29kZSANPj4Nc3RyZWFtDQpIic2X3VLjuBaFn6DfQXfDuaCP5X9fJiQEpkNI2eFQ
[......skipped......]
Ug0vSUQgWzxjNjIyNzFiYzY4YmFlYjY3YzBkM2ViNTk4MjJiZTA4Nz48YzYyMjcxYmM2OGJh
ZWI2N2MwZDNlYjU5ODIyYmUwODc+XQ0+Pg1zdGFydHhyZWYNODc1NA0lJUVPRg0=

--_===38330025====my.server.domain===_--

Чтобы создать сообщения, в которых MIME части (приложения) скопированы из других сообщений, хранящихся на Сервере, используйте вместо MIME элемента элемент copyMIME:

copyMIME

Атрибуты:

• folder или calendar

  имя открытого Представления папки или открытого Календаря.

• UID

  UID сообщения.

• partID в этом необязательном атрибуте задаётся часть сообщения, которую необходимо скопировать. Если он не указан, то копируется всё сообщение. Если же он указан, не-MIME заголовки части (отличные от Content-xxxxx) не копируются. Пример: Клиент сохраняет Заметку в Папке "Notes", добавляя части 3 и 4 (приложения) к сообщению 156, хранящегося в представлении папки INBOX:

C:<messageAppend id="A001" targetMailbox="Notes" flags="Seen">
    <EMail>
      <From realName="Sender Name">fromName@domain</From>
      <Subject>Vacation Pictures</Subject>
      <Date localTime="20060621T215124" timeShift="-25200">20070830T045124Z</Date>
      <Message-ID>web-40721383@domain.dom</Message-ID>
      <MIME type="multipart" subtype="mixed">
        <MIME type="text" subtype="plain">The first part of the underwater shots.</MIME>
        <copyMIME folder="INBOX" UID="156" partID="3"/>
        <copyMIME folder="INBOX" UID="156" partID="4"/>
      </MIME>
    </EMail>
  </messageAppend>
S:<response id="A001"/>

Вы можете прикладывать файлы, хранящиеся в Персональном Хранилище Файлов. Укажите полное имя файла в элементах MIME, используя атрибут fileName.
Вы должны явно указывать атрибуты type, subtype и (для текстовых файлов) атрибут charset.
Вы должны указать атрибут disposition-filename, так как атрибут fileName не используется для формирования имени приложенного файла.

Пример:
Клиент сохраняет Заметку в Папке "Notes", добавляя файл private/MyFile.jpg как приложение photo.jpg:

C:<messageAppend id="A001" targetMailbox="Notes" flags="Seen">
    <EMail>
      <From realName="Sender Name">fromName@domain</From>
      <Subject>Vacation Pictures</Subject>
      <Date localTime="20060621T215124" timeShift="-25200">20070830T045124Z</Date>
      <Message-ID>web-40721383@domain.dom</Message-ID>
      <MIME type="multipart" subtype="mixed">
        <MIME type="text" subtype="plain">Attached please find the images I have stored as files.</MIME>
        <MIME type="image" subtype="jpeg" fileName="private/MyFile.jpg" disposition-filename="photo.jpg" />
      </MIME>
    </EMail>
  </messageAppend>
S:<response id="A001"/>

Обратите внимание

Eсли для элемента <MIME /> значение атрибута disposition задано как none, то поле заголовка Content-Disposition: не создаётся, и поле Content-Type сохраняется без параметра name.

Обратите внимание

В качестве разделителя строк в текстовых частях MIME должен использоваться один символ перевода строки (0x0A, десятичное 10).

Вы можете попросить Сервер использовать "перетекающий" формат для MIME частей.

Пример:

C:<messageAppend id="A001" targetMailbox="Notes" flags="Seen">
    <EMail>
      <Subject>Test text</Subject>
      <MIME type="text" subtype="plain" format="flowed">This is a very long long long long long long long long long long superlong long long long long long long line, followed with a shorter line:
This is a shorter line.</MIME>
    </EMail>
  </messageAppend>
S:<response id="A001"/>

Эта операция добавляет в Папку следующее сообщение:

Subject: Test text
Content-Transfer-Encoding: 8bit
Content-Type: text/plain; format="flowed"; charset="utf-8"

This is a very long long long long long long long long long long superlong
long long long long long long line, followed with a shorter line:
This is a shorter line.

(после слова "superlong" есть концевой пробел)

Чтобы создать подписанное сообщение, убедитесь, что Закрытый Ключ разблокирован и укажите атрибут sign в самом верхнем элементе EMail.

C:<messageAppend id="A001" targetMailbox="Sent" flags="Seen,Answered" >
    <EMail sign="yes">
      <From realName="Sender Name">fromName@domain</From><Subject>I'll be there!</Subject>
      <To realName="Recipient Name">toName@domain</To><X-Mailer>SuperClient v7.77</X-Mailer>
      <MIME type="text" subtype="plain">Dear Susan,&#x0A;&#x0A;I will come to your place tomorrow, thank you for the invitation!&#x0A;Mary.&#x0A;</MIME>
    </EMail>
  </messageAppend>
S:<response id="A001"/>

Эта операция добавляет в Папку следующее сообщение:

From: "Sender Name" <fromName@domain>
Subject: I'll be there!
To: "Recipient Name" <toName@domain>
X-Mailer: SuperClient v7.77
Content-Type: multipart/signed; protocol="application/x-pkcs7-signature"; micalg="SHA1"; boundary="_===signed==2610002====my.server.domain===_"

This is a signed S/MIME message

--_===signed==2610002====my.server.domain===_
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit

Dear Susan,

I will come to your place tomorrow, thank you for the invitation!
Mary.

--_===signed==2610002====my.server.domain===_
Content-Type: application/x-pkcs7-signature; name="smime.p7s"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smime.p7s"

MIIE6wYJKoZIhvcNAQcCoIIE3DCCBNgCAQExCzAJBgUrDgMCGgUAMAsGCSqGSIb3DQEHAaCC
ArkwggK1MIICX6ADAgECAgcAk9RF+n/7MA0GCSqGSIb3DQEBBAUAMIG6MQswCQYDVQQGEwJV
UzELMAkGA1UECBMCQ0ExFDASBgNVBAcTC01pbGwgVmFsbGV5MSIwIAYDVQQKExlDb21tdW5p
.............
gIbXNT64QJ+gEYkI9mnePiS1TUOOzGYfXaLy1pqm6jmzBUt7/3UY8ZNHVIwM0Fzj7NwzqM1U
Esbkyi3WHNxTZ4HSCs8J2enGQEZjNWHOuX96xQojYGLV0m5Z/FatV9GQ8jNVBmQ9xYGKxmlY
jT9ze/oHyKuj7KR8QrgQSYiJVnn7

--_===signed==2610002====my.server.domain===_--

messageSubmit

Эта операция предписывает серверу сформировать Сообщение и передать его в Очередь для доставки. Копия сообщения может быть сохранена в Папке.

Атрибуты:

• useDSN

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

• targetMailbox, mailboxClass, flags, internalDate

  если необязательный атрибут targetMailbox указан, то созданное сообщение добавляется в указанную Папку. Эти атрибуты имеют тот же смысл, что и атрибуты операции messageAppend.

• dataset

  в этом необязательном атрибуте задаётся имя набора данных Пользователя. Все адреса получателей (смотрите ниже) сохраняются в указанную адресную книгу набора данных Пользователя, заменяя существующие дубликаты.

• UID

  необязательный атрибут для маркировки сообщения как отозванного при формировании сообщения на отзыв.

Тело:

XML представление Сообщения (элемент EMail) и ноль, один или несколько элементов Envelope-To. Каждый элемент Envelope-To должен иметь текстовое тело - адрес электронной почты, на который отправляется сообщение.
Если не указано ни одного элемента Envelope-To, то сообщение отправляется на адрес, указанный в элементах To, Cc и Bcc, находящихся внутри элемента EMail.
При формировании MIME текста сообщения все адреса, находящиеся в элементе Bcc, пропускаются.
Если элемент EMail содержит атрибут uploadID, RFC-тело письма копируется из указанного в этом атрибуте файла из "набора загруженных файлов" сессии.
Если представление XML не включает поля Message-ID, Date или MIME-Version, то сервер создаёт эти поля в сообщении. Пример:
Клиент отправляет простое текстовое сообщение на адрес toName@domain и его скрытую копию Bcc на адрес bccName@domain. Клиент запрашивает уведомление о доставке.

C:<messageSubmit id="A001" useDSN="yes" >
    <EMail>
      <From realName="Sender Name">fromName@domain</From>
      <Subject>I'll be there!</Subject>
      <To realName="Recipient Name">toName@domain</To>
      <X-Mailer>SuperClient v7.77</X-Mailer>
      <Bcc>bccName@domain</Bcc>
      <MIME type="text" subtype="plain">Dear Susan,&#x0A;&#x0A;I will come to your place tomorrow, thank you for the invitation!&#x0A;Mary.&#x0A;</MIME>
    </EMail>
  </messageSubmit>
S:<response id="A001"/>

Пример:
Клиент отправляет простое текстовое сообщение на адреса a1@domain и a2@domain (отличающиеся от адресов, указанных в элементах To и Cc).
Копия сообщения должна быть сохранена в Папке "Sent Items" с флагом Seen.
Клиент запрашивает уведомление о доставке.

C:<messageSubmit id="A001" targetMailbox="Sent Items" flags="Seen" >
    <Envelope-To>a1@domain address</Envelope-To>
    <Envelope-To>a2@domain address</Envelope-To>
    <EMail>
      <From realName="Sender Name">fromName@domain</From>
      <Subject>I'll be there!</Subject>
      <To realName="Recipient Name">toName@domain</To>
      <X-Mailer>SuperClient v7.77</X-Mailer>
      <Cc>ccName@domain</Cc>
      <MIME type="text" subtype="plain">Dear Susan,&#x0A;&#x0A;I will come to your place tomorrow, thank you for the invitation!&#x0A;Mary.&#x0A;</MIME>
    </EMail>
  </messageSubmit>
S:<response id="A001"/>

Пример:
Клиент пересылает сообщение 156, хранящееся в Представлении папки INBOX на адрес a1@domain:

C:<messageSubmit id="A001">
    <EMail>
      <From realName="Sender Name">fromName@domain</From>
      <Subject>Fwd: Sorry, I cannot make it :-(</Subject>
      <To realName="Recipient Name">a1@domain</To>
      <X-Mailer>SuperClient v7.77</X-Mailer>
      <MIME type="multipart" subtype="mixed">
        <MIME type="text" subtype="plain">Dear Susan,&#x0A;&#x0A;Attached please find the message I received this morning...&#x0A;Mary.&#x0A;</MIME>
        <copyMIME folder="INBOX" UID="156" />
    </EMail>
  </messageSubmit>
S:<response id="A001"/>

Эта операция добавляет в Папку следующее сообщение:

From: "Sender Name" <fromName@domain>
Subject: Fwd: Sorry, I cannot make it :-(
To: "Recipient Name" <toName@domain>
X-Mailer: SuperClient v7.77
Date: Wed, 21 Jun 2006 22:55:24 -0800
Message-ID: <ximss-38150012@this.server.dom>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="_===38330025====my.server.domain===_"

--_===38330025====my.server.domain===_
Content-Type: text/plain; charset="utf-8"

Dear Susan,

Attached please find the message I received this morning...
Mary.

--_===38330025====my.server.domain===_
Content-Type: message/rfc822

From: "Barbara Smith" <barbara@domain>
Subject: Sorry, I cannot make it :-(
To: "Sender Name" <fromName@domain>
X-Mailer: OtherClient v8.88
Date: Wed, 21 Jun 2006 21:51:24 -0800
Message-ID: <zzzzzzzzz@other.server.dom>
Content-Type: text/plain; charset="utf-8"

Mary,

Sorry, but I will be out of town tomorrow...

Barbara.

--_===38330025====my.server.domain===_--

Отзыв сообщения

Отдельно стоит рассмотреть сообщение об отзыве сообщения. Если сообщение folderReport содержит флаг RECALL в списке флагов <flags>, то такое письмо можно отозвать. Сообщение submitMessage должно содержать специальный заголовок X-Special-Delivery со значением recall <Message-Id>, где Message-Id - это идентификатор отзываемого сообщения, взятый из заголовка Message-ID отзываемого письма. В атрибутах submitMessage также желательно указать UID отзываемого сообщения для его корректной маркировки как отозванного.

Обратите внимание

Если сообщение уже было отозвано, то folderReport будет содержать флаг Recalled.

Return-Path: <john.smith@domain.com>
Received: from [::1] (account john.smith@domain.com)
  by domain.com (CommuniGate Pro XIMSS 6.5.1)
  with HTTPU id 859730003 for karen.johnson@domain.com; Mon, 01 May 2025 09:00:00 +0300
X-Mailer: CommuniGate Pronto! HTML5 6.5.1
Subject: Recall: hi
MIME-Version: 1.0
X-Special-Delivery: recall <ximss-859720008@domain.com>
From:  "Джон Смит" <john.smith@domain.com>
To:  "Karen Johnson" <karen.johnson@domain.com>
Date: Mon, 01 May 2025 09:00:00 +0300
Message-ID: <ximss-859730014@domain.com>
Content-Type: text/plain; charset="utf-8"; format="flowed"
Content-Transfer-Encoding: 8bit

Джон Смит желает отозвать сообщение, отправленное ранее.
Оно было отправлено по ошибке.

Сервер может сам подготовить письмо для отзыва на основе отзываемого письма, для этого ему необходимо отправить сообщение folderRead, указав отзываемому письму mode="recall":

C:<folderRead mode="recall" folder="Sent Items-MM-1" UID="482" totalSizeLimit="204800" id="37"/>

S:<folderMessage folder="Sent Items-MM-1" id="37" mode="recall" UID="482" INTERNALDATE="20250605T115336Z" localTime="20250605T145336">
    <EMail>
      <From realName="Джон Смит">john.smith@domain.com</From>
      <Subject>Recall: hi</Subject>
      <X-Special-Delivery>&#32;recall &lt;ximss-859730014@domain.com&gt;</X-Special-Delivery>
      <To realName="Karen Johnson">karen.johnson@domain.com</To>
      <MIME subtype="plain" type="text">&#10;&#10;&#10;Джон Смит желает отозвать сообщение, отправленное ранее.&#10;Оно было отправлено по ошибке.&#10;&#10;</MIME>
      <flags>Answered,Seen</flags>
    </EMail>
  </folderMessage>
S:<response id="37"/>

Пример сообщения для отзыва:

C:<messageSubmit mailboxClass="" flags="Seen" dataset="RecentAddresses" UID="482" id="37">
    <EMail charset="utf-8">
      <X-Mailer>CommuniGate Pronto! HTML5 6.5.1</X-Mailer>
      <To realName="Karen Johnson">karen.johnson@domain.com</To>
      <Subject>Recall: hi</Subject>
      <MIME-Version>1.0</MIME-Version>
      <X-Special-Delivery> recall &lt;ximss-859730014@domain.com&gt;</X-Special-Delivery>
      <MIME type="text" subtype="plain" charset="utf-8" format="flowed">Джон Смит желает отозвать сообщение, отправленное ранее. Оно было отправлено по ошибке.</MIME>
      <From realName="Джон Смит">john.smith@domain.com</From>
    </EMail>
  </messageSubmit>
S:<response id="37"/>

Обратите внимание

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

messageRedirect

Эта операция предписывает серверу сформировать копию сообщения, хранящегося в Папке и передать его в Очередь для доставки.

Атрибуты:

• folder

  имя Представления папки.

• UID

  UID сообщения.

• partID

  в этом необязательном атрибуте задаётся часть сообщения, которую необходимо прочитать. Если он не указан, то перенаправляется всё сообщение. Если оно присутствует, то оно должно указывать на часть сообщения, которое является E-mail сообщением: раздел контейнера message/rfc822, дайджест и т.п.

• mirror

  если этот необязательный атрибут есть и установлен в yes, сообщение "отражается": оно отправляется на указанные адреса, но его заголовки To и Cc не меняются.

• markRedirected

  если этот атрибут установлен в yes, оригинальному сообщению проставляется флаг "Redirected".
  Если атрибут не задан, то подразумевается значение yes, когда атрибут partID не задан, иначе используется значение no.

Тело:

Набор из одного или более элементов To задаёт адрес(а) получателя (получателей).

Пример:
Клиент перенаправляет сообщение 156, хранящееся в Представлении папки INBOX на адреса a1@domain и a2@domain:

C:<messageRedirect id="A001" folder="INBOX" UID="156">
    <To realName="Recipient Name">a1@domain</To>
    <To realName="Recipient-2">a2@domain</To>
  </messageRedirect>
S:<response id="A001"/>

messageForward

Эта операция предписывает серверу сформировать копию сообщения, хранящегося в Папке и передать его в Очередь для доставки. Операция использует те же атрибуты, что и операция messageRedirect, но атрибут mirror не поддерживается.

messageConfirm

Эта операция предписывает серверу сформировать MDN-уведомление (Уведомление об Открытии Сообщения) для сохранённого в папке сообщения и передать его в Очередь для доставки.
Клиентские приложения должны использовать эту операцию в следующих случаях:

• сообщение было показано пользователю, и
• сообщение имеет поле заголовка Disposition-Notification, и
• сообщения не имеет флага $MDNSent, и
• Настройка пользователя SendMDNMode установлена в значение Automatically или установлена в значение Manually и пользователь явно потребовал отправить подтверждение.

Атрибуты:

• folder

  имя Представления папки.

• UID

  UID сообщения.

• type

  этот атрибут должно быть установлен в auto (если подтверждение генерируется автоматически) или в manual (если пользователь явно затребовал отправку подтверждения).

messageAttrRead

Эта операция читает атрибуты сообщения в Папке.

Атрибуты:

• folder

  имя Представления папки.

• UID

  UID сообщения.

• Тело:

набор элементов XML field. Каждый элемент должен иметь текстовое тело, содержащее имя получаемого атрибута. Если ни один элемент field не указан, то возвращаются все атрибуты.
Сервер возвращает сообщение messageAttrData.

messageAttrWrite

Эта операция изменяет атрибуты сообщения в Папке.

Атрибуты:

• folder

  имя Представления папки.

• UID

  UID сообщения.

• Тело:

XML представление словаря с новыми значениями атрибутов. Для удаления атрибута укажите для него пустое () значение.

Сервер присылает следующие сообщения с данными:

folderMessage

Это синхронное сообщение с данными отправляется, когда Сервер обрабатывает запрос folderRead.

Атрибуты:

• folder, UID, partID, mode

  копии атрибутов запроса folderRead.

• INTERNALDATE

  Метаданные сообщения - его отметка времени UTC.

• localTime

  Метаданные сообщения - его отметка времени с учётом таймзоны.

• RECALLUNTIL

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

• Тело:

XML представление Сообщения или его части.

messageAdded

Эти синхронные сообщения с данными присылаются, когда Сервер обрабатывает запросы messageAppend, contactAppend и messageCopy с установленными атрибутами report.

Атрибуты:

• folder или targetMailbox

  имя Представления папки или Папки-приёмника, скопированное из соответствующего атрибута запроса.

• UID

  UID добавленного сообщения.

Обратите внимание

даже если это сообщение данных отправлено, Сервер всё равно будет отправлять асинхронные сообщения данных folderReport, уведомляющие клиентов о том, что в Представление папки было добавлено новое сообщение. Клиент ДОЛЖЕН использовать операцию folderSync для синхронизации своего внутреннего вида с видом Сервера, в противном случае вновь добавленные сообщения не будут "видны" в Представлении папки.

messageAttrData

Эти синхронные сообщения с данными отправляются, когда Сервер обрабатывает запрос messageAttrRead.

Атрибуты:

• folder, UID

  копируются из соответствующего атрибута запроса.

Тело:

XML представление словаря с атрибутами.

Управление Пользователем

Для управления Списками Прав Доступа Пользователя (ACL) клиент может использовать следующий набор операций.

accountRightsGet

Эта операция заставляет Сервер отправить сообщение с данными accountRights с правами доступа текущего или указанного Пользователя.

Атрибуты:

• userName

  (необязательно) задаёт имя требуемого Пользователя. Если этот атрибут отсутствует, то используется текущий Пользователь.

accountACLList

Эта операция заставляет Сервер отправить сообщение с данными accountACL, содержащее данные из Списка Прав Доступа к Папке.

Атрибуты:

• userName

  (необязательно) задаёт имя требуемого Пользователя. Если этот атрибут отсутствует, то используется текущий Пользователь.

accountACLUpdate

Эта операция изменяет Список Прав Доступа Пользователя.

Атрибуты:

• userName

  (необязательно) задаёт имя требуемого Пользователя. Если этот атрибут отсутствует, то используется текущий Пользователь.

Тело:

Набор элементов XML aclElem. Эти элементы аналогичны используемым в операции mailboxACLUpdate , но в строках их тела применяются символы, которые задают Права Доступа Пользователя.

Сервер присылает следующие сообщения с данными:

accountRights

Это сообщение отправляется, когда Сервер обрабатывает запрос accountRightsGet.

Атрибуты:

• userName

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

Тело:

строка; каждый символ определяет фактически действующие Права Доступа Пользователя, предоставленные текущему пользователю.

accountACL

Это сообщение отправляется, когда Сервер обрабатывает запрос accountACLList.

Атрибуты:

• userName

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

Тело:

Набор XML элементов aclElem, один элемент для каждого элемента из Списка Прав Доступа Пользователя; аналогично используемым в сообщениях данных mailboxACL, но строки тела элемента содержат символы, представляющие Права Доступа Пользователя.

Безопасный обмен Сообщениями (S/MIME)

Для задействования возможностей Сервера по работе с S/MIME, клиент может использовать следующий набор операций.

SMIMEUnlock

Эта операция разблокирует Закрытый Ключ Пользователя, хранящийся на Сервере.
Когда Закрытый Ключ разблокирован, Сервер расшифровывает части сообщений с использованием операции folderRead.
Сервер также может зашифровывать и/или подписывать цифровой подписью передаваемые сообщения.

Обратите внимание

Эта операция передаёт разблокирующую строку ("пароль хранения") открытым текстом. Клиентское приложение должно использовать эту команду только через безопасное (TLS) соединение.

Обратите внимание

Разблокированный Закрытый Ключ добавляется только к данным текущей сессии и нигде не сохраняется. Если для одного и того же Пользователя открывается другая сессия, то ему необходимо самостоятельно разблокировать в ней Закрытый Ключ.

Атрибуты:

• password

  разблокирующая строка (пароль).

• duration

  необязательный атрибут: время (в секундах), в течение которого Закрытый Ключ будет находиться разблокированным; по истечении этого времени Закрытый Ключ блокируется автоматически.

SMIMELock

Эта операция блокирует Закрытый Ключ Пользователя, хранящийся на Сервере (она удаляет разблокированный Закрытый Ключ из данных текущей сессии).
Эту операцию рекомендуется использовать после определённого времени бездействия пользователя.

SMIMEModifyPassword

Эта операция изменяет парольную строку, защищающую Закрытый Ключ Пользователя на Сервере. Закрытый Ключ Пользователя должен быть разблокирован.

Обратите внимание

Эта операция передаёт разблокирующую строку ("пароль хранения") открытым текстом. Клиентское приложение должно использовать эту команду только через безопасное (TLS) соединение.

Атрибуты:

• password

  новая разблокирующая строка (пароль).

SMIMEGet

Эта операция читает с Сервера конфигурацию S/MIME Пользователя.

• Атрибуты:

• type

  тип запрашиваемой информации. Если значение атрибута type равно certificate, Сервер присылает сообщение с данными certificate, содержащее Публичный Сертификат Пользователя.

SMIMESet

Эта операция изменяет на Сервере конфигурацию S/MIME Пользователя.

Атрибуты:

• mode

  операции: add, new, update, delete.

• password

  пароль разблокировки S/MIME (нужен для операций add и new).

• filePassword

  пароль для расшифровки импортируемых данных (нужен для операций add и delete).

• duration

  сразу после установки новых S/MIME ключа и сертификата они остаются разблокированными. Если этот атрибут установлен, он задаёт время в секундах, в течение которого Частный ключ остаётся разблокированным.

• PFX

  этот атрибут используется, если тело запроса не содержит XML элемента с данными PFX. Этот атрибут указывает на файл в "наборе загруженных файлов". Файл в формате PKCS12 должен содержать Закрытый ключ и сертификат.

Тело:

необязательно: элемент PFX; он должен содержать элемент XML base64 с текстовым телом - данными PKCS12, кодированными методом Base64 и содержащими Закрытый ключ и сертификат.

Если значение атрибута mode равно add, Сервер использует данные PKCS12 из XML элемента PFX в теле запроса или из файла, указанного в атрибуте PFX, расшифрует их с помощью значения filePassword в качестве пароля и устанавливает в текущем Пользователе Закрытый ключ и Сертификат.
Сервер шифрует данные Закрытого ключа, используя заданный в атрибуте password пароль, который становится "строкой разблокирования S/MIME".

Если значение атрибута mode равно new, Сервер создаёт случайный закрытый ключ и выдаёт Сертификат S/MIME для текущего Пользователя, подписанный сертификатом "Издателя S/MIME" домена Пользователя.
Сервер шифрует данные Закрытого ключа, используя заданный в атрибуте password пароль, который становится "строкой разблокирования S/MIME".

Если значение атрибута mode равно update, Сервер обновляет Сертификат S/MIME для текущего Пользователя, если он был подписан сертификатом "Издателя S/MIME" домена Пользователя.

Если значение атрибута mode равно delete, Сервер использует данные PKCS12 из XML элемента PFX в теле запроса или из файла, указанного в атрибуте PFX, расшифрует их с помощью значения filePassword в качестве пароля и сравнивает расшифрованный Закрытый ключ с Закрытым ключом в S/MIME данных в текущего Пользователя.
Если Ключи совпадают, то Закрытый Ключ и Сертификат удаляются из данных S/MIME Пользователя.

Обратите внимание

Эта операция передаёт разблокирующую строку ("пароль хранения") открытым текстом. Клиентское приложение должно использовать эту команду только через безопасное (TLS) соединение.

Сервер присылает следующие сообщения с данными:

certificate

Это сообщение отправляется, когда Сервер обрабатывает запрос SMIMEGet.

• Тело:

  представление XML Публичного Сертификата S/MIME Пользователя.

Сервер находит все подписанные части сообщения и пытается проверить, что тело части не изменялось с момента подписания, и что сертификаты корректны (то есть, были выпущены известными центрами сертификации).

Тело элемента MIME для подписанной части сообщения содержит два XML подэлемента: первым элементом являются подписанные данные (элемент EMail или MIME), а второй частью является XML элемент SMIMESignature.

Если Сервер не смог раскодировать или расшифровать данные подписи, то тело элемента MIME для подписанной части сообщения содержит атрибут decryptionError c текстом кода ошибки.

Тело элемента SMIMESignature содержит подэлементы Certificate для всех подписей, соответствующим данным части. Если Сервер не смог проверить Сертификат, то его элемент содержит атрибут validationError с текстом кода ошибки. Если данным части не соответствует никакая подпись, то элемент SMIMESignature является пустым.

Пример:
Клиент зачитывает подписанное сообщение:

C:<folderRead id="A001" folder="INBOX" UID="55" totalSizeLimit="100000" />
S:<folderMessage id="A001" folder="INBOX" UID="55">
  <EMail>
    <Return-Path>fromName@domain</Return-Path>
    <From realName="Sender Name">fromName@domain</From>
    <Subject>Re: I'll be there!</Subject>
    <To realName="Recipient Name">a1@domain</To>
    <X-Mailer>SuperClient v7.77</X-Mailer>
    <Date localTime="20070830T204318" timeShift="-25200">20070830T184318Z</Date>
    <Message-ID>web-40721383@domain.dom</Message-ID>
    <MIME digesterName="SHA1" estimatedSize="5171" subtype="signed" type="multipart"
           Type-micalg="SHA1" Type-protocol="application/x-pkcs7-signature" />
      <MIME estimatedSize="3032" partID="01" subtype="mixed" type="multipart">
        <MIME charset="utf-8" estimatedSize="86" partID="01-01" subtype="plain" type="text">Dear Susan,&#x0A;&#x0A;Attached please find a file I received this morning...&#x0A;Mary.&#x0A;
        </MIME>
        <MIME disposition="attachment" Disposition-filename="logo.gif" estimatedSize="1929" partID="01-02" subtype="gif" type="image" />
      </MIME>
      <SMIMESignature>
        <x509 subject="fromName@domain" validationError="presented certificate is issued by an unknown authority" version="2">
          <subject><cn>Sender Name</cn><contact>fromName@domain</contact></subject>
          <issuer><c>US</c><cn>issuer.dom</cn><contact>postmaster@issuer.dom</contact><l>Moscow</l>
                  <o>Issuer Company, Inc.</o><ou>Issuer Department</ou><st>CA</st></issuer>
          <validFrom>20040924T231857Z</validFrom>
          <validTill>20170923T231857Z</validTill>
        </x509>
      </SMIMESignature>
    </MIME>
  </EMail>
  </folderMessage>
S:<response id="A001"/>

Если Закрытый Ключ Пользователя разблокирован, то Сервер пытается расшифровать все зашифрованные части сообщения.

• Если расшифровка заканчивается неудачно, то элемент для зашифрованной части содержит дополнительный атрибут:

• decryptionError

  текст сообщения об ошибке расшифровки.

Если расшифровка заканчивается неудачно, то зашифрованная часть показывается как XML подэлемент MIME или EMail элемента зашифрованной части.

Если расшифровка заканчивается успешно, то тело элемента зашифрованной части содержит XML подэлемент MIME или EMail с расшифрованными данными.

• Элемент зашифрованной части содержит дополнительные атрибуты:

• cipherName

  имя криптографического шифра, использованного для расшифровки шифрованной части.

• keyLength

  длина (в битах) использованного для шифрования зашифрованной части ключа криптографического шифра.

Пример:
Клиент зачитывает зашифрованное сообщение, затем разблокирует Закрытый Ключ Пользователя и потом повторно зачитывает то же самое сообщение:

C:<folderRead id="A001" folder="INBOX" UID="55" totalSizeLimit="100000" />
S:<folderMessage id="A001" folder="INBOX" UID="55">
  <EMail>
    <Return-Path>fromName@domain</Return-Path>
    <From realName="Sender Name">fromName@domain</From>
    <Subject>Re: I'll be there!</Subject>
    <To realName="Recipient Name">a1@domain</To>
    <X-Mailer>SuperClient v7.77</X-Mailer>
    <Date localTime="20070830T204318" timeShift="-25200">20070830T184318Z</Date>
    <Message-ID>web-40721383@domain.dom</Message-ID>
    <MIME disposition="attachment" Disposition-filename="smime.p7m" estimatedSize="4536"
           subtype="x-pkcs7-mime" type="application" Type-name="smime.p7m" Type-smime-type="enveloped-data" />
  </EMail>
  </folderMessage>
S:<response id="A001"/>
C:<SMIMEUnlock id="A002" password="smime-password" />
S:<response id="A002"/>
C:<folderRead id="A003" folder="INBOX" UID="55" totalSizeLimit="100000" />
S:<folderMessage id="A003" folder="INBOX" UID="55">
  <EMail>
    <Return-Path>fromName@domain</Return-Path>
    <From realName="Sender Name">fromName@domain</From>
    <Subject>Re: I'll be there!</Subject>
    <To realName="Recipient Name">a1@domain</To>
    <X-Mailer>SuperClient v7.77</X-Mailer>
    <Date localTime="20070830T204318" timeShift="-25200">20070830T184318Z</Date>
    <Message-ID>web-40721383@domain.dom</Message-ID>
    <MIME cipherName="RC2" disposition="attachment" Disposition-filename="smime.p7m" estimatedSize="4536" keyLength="40"
          subtype="x-pkcs7-mime" type="application" Type-name="smime.p7m" Type-smime-type="enveloped-data" >
      <EMail partID="E">
        <From realName="Sender Name">fromName@domain</From>
        <Subject>Re: I'll be there!</Subject>
        <To realName="Recipient Name">a1@domain</To>
        <X-Mailer>SuperClient v7.77</X-Mailer>
        <Date localTime="20070830T204318" timeShift="-25200">20070830T184318Z</Date>
        <Message-ID>web-40721383@domain.dom</Message-ID>
        <MIME estimatedSize="3275" partID="E" subtype="mixed" type="multipart">
          <MIME charset="utf-8" estimatedSize="329" partID="E-01" subtype="plain" type="text" Type-format="flowed">
            This is an encrypted E-mail with an attachment.

            On Thu, 30 Aug 2007 20:40:49 -0800
            &quot;Sender Name&quot; &lt;fromName@domain&gt; wrote:
            &gt; Dear Susan,
            &gt;
            &gt; I will come to your place tomorrow, thank you for the invitation!
            &gt; Mary.
          </MIME>
          <MIME disposition="attachment" Disposition-filename="logo.gif" estimatedSize="1929" partID="E-02"
                subtype="gif" type="image" />
        </MIME>
      </EMail>
    </MIME>
  </EMail>
</folderMessage>
S:<response id="A003"/>

Когда Закрытый Ключ Пользователя разблокирован, клиент может передать подписанное сообщение электронной почты.

• Элемент EMail должен содержать дополнительный атрибут:

  • sign

    если этот необязательный атрибут задан со значением yes, то тело сообщения будет подписано.

Пример:
Клиент отправляет подписанное сообщение на адрес toName@domain.

C:<messageSubmit id="A001">
    <EMail sign="yes">
      <From realName="Sender Name">fromName@domain</From>
      <Subject>I'll be there!</Subject>
      <To realName="Recipient Name">toName@domain</To>
      <X-Mailer>SuperClient v7.77</X-Mailer>
      <MIME type="text" subtype="plain">Dear Susan,&#x0A;&#x0A;I will come to your place tomorrow, thank you for the invitation!&#x0A;Mary.&#x0A;</MIME>
    </EMail>
  </messageSubmit>
S:<response id="A001"/>

Когда Закрытый Ключ Пользователя разблокирован, клиент может передать зашифрованное сообщение при условии, что в Адресной Книге содержатся соответствующие записи для всех получателей этого сообщения и для каждой из этих записей имеется PKI Сертификат получателя.

• Элемент EMail верхнего уровня должен содержать дополнительные атрибуты:

  • encrypt

    если этот атрибут существует и его значением является yes, то тело сообщения будет зашифровано.

  • addressBook

    имя Адресной Книги, в которой будет осуществляться поиск сертификатов получателей.

  • addressBook1, addressBook2

    необязательно: имена дополнительных Адресных Книг. Если сертификаты получателей не были найдены в Адресной Книге с именем из атрибута addressBook, проверяются эти Адресные Книги.

Элемент EMail верхнего уровня должен содержать один "внутренний" элемент EMail - содержимое этого элемента будет зашифровано. Поля заголовков внутреннего элемента EMail могут как совпадать с аналогичными заголовками в элементе EMail верхнего уровня, так и различаться. Например, элемент Subject "внутреннего" элемента EMail может отличаться.

Обратите внимание

Вы не можете указать оба атрибута sign и encrypt для элемента EMail верхнего уровня. Для отправки зашифрованного и подписанного сообщения, добавьте атрибут sign к внутреннему элементу EMail.

Пример:
Клиент отправляет зашифрованное и подписанное текстовое сообщение на адрес toName@domain. Обратите внимание на несовпадающие поля Тема. Клиент запрашивает уведомление о доставке.

C:<messageSubmit id="A001" useDSN="yes" >
    <EMail encrypt="yes" addressBook="Contacts" >
      <From realName="Sender Name">fromName@domain</From>
      <Subject>A message regarding your request</Subject>
      <To realName="Recipient Name">toName@domain</To>
      <EMail sign="yes">
        <From realName="Sender Name">fromName@domain</From>
        <Subject>I'll be there!</Subject>
        <To realName="Recipient Name">toName@domain</To>
        <X-Mailer>SuperClient v7.77</X-Mailer>
        <MIME type="text" subtype="plain">Dear Susan,&#x0A;&#x0A;I will come to your place tomorrow, thank you for the invitation!&#x0A;Mary.&#x0A;</MIME>
      </EMail>
    </EMail>
  </messageSubmit>
S:<response id="A001"/>

Операции с Контактами

Информация о контактах (vCard и vCardGroup) может быть сохранена в любой Папке как сообщение. Элемент данных vCard может быть приложен (как MIME часть) к любому сообщению электронной почты. Каждое сообщение может содержать несколько MIME частей, содержащих несколько объектов vCard.

MIME части с типом text и x-vcard или с подтипом dictionary содержат элементы vCard.

MIME части с типом text и x-group содержат один элемент vCardGroup.

Чтобы включить данные vCard в сообщение (используя операции messageAppend, messageSubmit, включите элемент MIME с атрибутами type="text" и subtype="directory". Тело элемента должно содержать один или более элементов vCard.

Для включения данных vCardGroup в сообщение (используя операции messageAppend, messageSubmit) добавьте элемент MIME с атрибутами type="text" и subtype="x-vgroup". Тело элемента должно содержать один элемент vCardGroup.

Папки класса Контакты используются для хранения специальных сообщений ("элементов данных"), в которых содержатся только данные vCard или vCardGroup. В правильно сформированном элементе vCard:

• в поле Subject содержится атрибут FN данных vCard.
• в поле To содержится атрибуты EMAIL данных vCard.
• в поле X-Telnum содержатся атрибуты TEL данных vCard.
• поле X-Has-Certificate существует и содержит значение true, если vCard имеет атрибут KEY.

В правильно сформированном элементе данных vCardGroup:

• в поле Subject содержится атрибут NAME данных vCardGroup.

Используйте следующие операции для формирования, сохранения и получения этих специальных сообщений:

contactAppend

Эта операция создаёт специальное сообщение электронной почты, в теле которого содержатся данные vCard или vCardGroup, а также формирует все необходимые поля заголовка сообщения электронной почты и сохраняет получившееся сообщение в указанной Папке или в Представлении Папки.

Атрибуты:

• folder

  имя целевого Представления папки. Если оно указано, то атрибут targetMailbox игнорируется.

• targetMailbox

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

• flags, replacesUID, replaceMode, report

  эти необязательные атрибуты имеют тот же смысл, что и атрибуты операции messageAppend. Если атрибут flags не указан, его значение подразумевается равным Seen.

Тело:

ровно один элемент vCard или vCardGroup. Операция добавляет атрибуты vCard UID и FN в случае, если они отсутствуют.

Пример 1:
Клиент добавляет объект vCard в Папку Contacts.

C:<contactAppend id="A011" targetMailbox="Contacts" >
    <vCard>
      <NAME>Bjorn Jensen</NAME>
      <N><FAMILY>Jensen</FAMILY><GIVEN>bjorn</GIVEN>
        <MIDDLE>A</MIDDLE><PREFIX>Mr.</PREFIX><SUFFIX>II</SUFFIX></N>
      <EMAIL><INTERNET /><USERID>bjorn@domain.dom</USERID></EMAIL>
      <TEL><WORK /><VOICE /><MSG /><NUMBER>+1 313 747-4454</NUMBER></TEL>
      <KEY><x509 /><BINVAL>dGhpcyBjb3VsZCBiZSAKbXkgY2VydGlmaWNhdGUK</BINVAL></KEY>
    </vCard>
  </contactAppend>
S:<response id="A011"/>

contactsImport

Эта операция разбирает загруженный файл, в котором должны содержаться элементы vCard. Получившиеся элементы копируются в специальное Представление папки.

Атрибуты:

• folder

  имя Представления папки.

• uploadID

  строка, идентифицирующая файл в "наборе загруженных файлов".

contactFind

Эта операция осуществляет поиск в открытом Представлении папки сообщения vCard с адресом электронной почты или телефонным номером, соответствующим указанному адресу.
Когда требуется "нечёткий" поиск, операция ищет объекты vCard, содержащие строку поиска в атрибутах почтовых адресов, телефонов или Имён Хранения (File As) в виде подстроки.
Проверяются только поля заголовков сообщения электронной почты (To и X-Telnum), а не фактические данные vCard.

Атрибуты:

• folder

  имя Представления папки.

• totalSizeLimit

  аналогично операции folderRead. Если устанавливается значение, равное нулю, то тело vCard не зачитывается.

• peer

  искомый адрес.

• limit

  необязательный параметр, ограничивающий количество найденных объектов. Операция завершается, когда найдено запрашиваемое количество подходящих объектов или после просмотра всей Папки.

• mode

  если этот атрибут задан и имеет значение sub, то применяется "нечёткий" поиск.
  Содержимое обнаруженного объекта vCard отправляется клиенту как сообщение с данными folderMessage со следующими дополнительными атрибутами:

Атрибуты:

• folder, peer

  имеют те же значения, что и в запросе.

• UID

  число: UID найденного сообщения с данными vCard.

• foundAddress

  необязательно: элемент адреса To или X-Telnum, который соответствует значению peer.

• peerName

  необязательно: атрибут Имя Хранения (File As) найденного объекта vCard.

Операции с Календарём

Клиент может использовать следующие операции для работы с Календарём аутентифицированного Пользователя, а также с Календарями других Пользователей (указывая полное имя Папки в виде ~accountName@domainName/mailboxName).

calendarOpen

Эта операция открывает указанную Папку как "Календарь".
Календарь представляет собой Папку Сервера, в которой сообщения были разобраны, и из которых была получена вся календарная информация. Или же, Календарь может представлять собой документ формата iCalendar (набор событий iCalendar), полученный по протоколу HTTP/HTTPS с указанного URL.
Каждый календарь имеет имя; в одной сессии не может быть двух календарей с одинаковыми именами. С другой стороны, в одной сессии могут быть открыто два различных календаря (с разными именами) для одной и той же Папки.

Атрибуты:

• calendar

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

• url

  если указан - URL объекта iCalendar на внешнем сервере. Объект зачитывается, разбирается, и все его объекты VEVENT используются в качестве данных Календаря. В этом случае Папка на Сервере не используется.

• mailbox

  имя Папки. Этот атрибут используется, если не указан атрибут url. Если этот атрибут не указан, то используется имя календаря (атрибут calendar).
  Сессия может использовать несколько Календарей одновременно.

calendarClose

Эта операция закрывает открытый Календарь.

Атрибуты:

• calendar

  имя Календаря.

findEvents

Эта операция получает объекты VEVENT из указанного Календаря. Будут получены только те События (Встречи), которые попадают в указанный временной интервал.

Атрибуты:

• calendar

  имя Календаря.

• timeFrom, timeTill

  начало и конец временного интервала (значения времени должны быть указаны для выбранного часового пояса).

• byAlarm

  если этот необязательный атрибут задан со значением yes, то операция ищет не События (Встречи) в указанном временном интервале, а такие События (встречи), элемент Alert (Напоминание) которых задан в указанном временном интервале.

• limit

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

• skip

  этот необязательный числовой атрибут указывает, сколько из "возвращаемых" Событий должно быть пропущено. Используя этот атрибут, клиент может получать большой набор Событий по "кусочкам". Сервер отправляет сообщение с данными events для каждых 24-часовых суток (в выбранном часовом поясе) из указанного временного интервала.

findTasks

Эта операция получает объекты VTODO из указанного Календаря. Будут получены только те Задания, которые попадают в указанный временной интервал.

Атрибуты:

• calendar, timeFrom, timeTill, byAlarm, limit, skip

  эти атрибуты имеют тот же смысл, что и в операции findEvents. Сервер отправляет сообщение с данными tasks для каждых 24-часовых суток (в выбранном часовом поясе) из указанного временного интервала.

calendarRead

Эта операция запрашивает у Сервера Сообщение или его часть. Оно отправляется клиенту как сообщение с данными calendarMessage.
Эта операция аналогична операции folderRead, но вместо атрибута folder она использует атрибут calendar для указания имени открытого Календаря.

Обратите внимание

Эта операция не может применяться к объекту Календаря, построенному с использованием внешнего (заданного с помощью URL) объекта iCalendar. Для таких объектов используйте операцию calendarReadItem.

calendarReadItem

Эта операция запрашивает у Сервера календарный объект. Он отправляется клиенту как сообщение с данными calendarItem.

Атрибуты:

• calendar

  имя Календаря.

• UID

  число: UID объекта.

calendarPublish

Эта операция помещает календарный объект в Календарь. Существующие элементы данных, имеющие тот же UID, удаляются.

Атрибуты:

• calendar

  имя Календаря.

• sendRequests

  если этот необязательный атрибут задан и его значением является no, то событие сохраняется без рассылки уведомления другим участникам.
  В противном случае, если ранее существовало событие с таким же UID, то отправляются запросы на Отмену всем тем участникам старого события, которых нет в новом событии.
  Запрос на встречу или указание задания отправляется всем участникам, или, если значением атрибута является new, только новым участникам.

• copyExceptions

  если этот необязательный атрибут не установлен в no и объект не содержит recurrenceID, а Календарь уже содержит объект с таким же UID, все исключения повторяющихся событий копируются в новый объект.

Тело:

Объект iCalendar для помещения в выбранный Календарь и необязательные элементы MIME и/или copyMIME для добавления (аналогично элементам, используемым в операции messageAppend).
Если не передано элементов MIME или copyMIME, а в Календаре есть объект с таким же UID, приложения копируются из того объекта. Если такое поведение не нужно, включите постой объект noMIME. Объект iCalendar может содержать объекты vtimezone и должен содержать ровно одно событие.
Объект vtimezone, можно не включать в календарный объект, если он указывает на часовой пояс, который является одним из стандартных часовых поясов, известных серверу.
Можно также не указывать название часового пояса в атрибутах даты, содержащих значения без суффикса Z. В этом случае используется часовой пояс, выбранный в Настройках текущего Пользователя.
Если событие не содержит элемента UID, то Сервер генерирует такой уникальный UID и добавляет его к событию.
Чтобы создать или обновить объект исключения повторяющегося события, включите в объект vevent атрибут recurrenceID.

Пример 1:
Клиент публикует объект iCalendar в календаре Calendar.

C:<calendarPublish id="A021" calendar="Calendar">
   <iCalendar xmlns="urn:ietf:params:xml:ns:xcal">
    <vCalendar method="PUBLISH" prodid="CommuniGate Pro 5.1.7" version="2.0">
     <vevent>
      <organizer CN="Big Boss">MAILTO:boss@company.dom</organizer>
      <attendee CN="Small Boy">MAILTO:boy@company.dom</attendee>
      <rrule>FREQ=WEEKLY;BYDAY=MO,TH</rrule>
      <dtstamp>20061022T091143Z</dtstamp>
      <uid>18927897984@kjjkjkjk-123444</uid>
      <sequence>0</sequence>
      <summary>Report Meeting</summary>
      <dtstart tzid="NorthAmerica/Pacific">20060515T100000</dtstart>
      <dtend tzid="NorthAmerica/Pacific">20060515T110000</dtend>
      <busystatus>BUSY</busystatus>
      <last-modified>20060516T034850Z</last-modified>
      <created>20060516T034850Z</created>
      <priority>5</priority>
      <description>A twice-a-week meeting to discuss the progress of the assigned projects.</description>
     </vevent>
    </vCalendar>
   </iCalendar>
   <MIME uploadID="att01" />
   <copyMIME folder="INBOX" UID="156" partID="3"/>
  </calendarPublish>
S:<response id="A021"/>

Обратите внимание

Если значение времени указывается без суффикса "Z", то подразумевается местное время в Часовом Поясе, выбранном для текущего пользователя.

calendarCancel

Эта операция удаляет событие из Календаря. Всем участникам отправляются запросы для отмены события.

Атрибуты:

• calendar

  имя Календаря.

• UID

  необязательно; UID сообщения (числовой).

• itemUID

  необязательно; строка с UID записи о Событии (iCalendar).

• recurrenceId

  необязательно; отметка времени идентификатора повторяющегося события.

• sendRequests

  если значением этого необязательного атрибута является no, то всем приглашённым на встречу не отправляются сообщения с запросами для отмены события.

Тело:

• необязательный объект iCalendar, который необходимо отменить.
  Если это событие не указано, то из Календаря берётся запись с заданным UID События iCalendar или с заданным UID сообщения. Затем все записи с одинаковыми UID записи События (iCalendar) удаляются.
• необязательный объект requestComment, содержащий текстовое тело - комментарий, включаемый в сообщение с запросом для отмены события.

Чтобы отменить только одно Событие из серии повторяющихся событий передайте либо объект iCalendar с атрибутом recurrenceId, либо, если объект iCalendar не указан, используйте атрибут recurrenceId.

Если удаляется последний экземпляр серии повторяющихся событий, сервер вызывает vcsDeleteConf, инициируя удаление связанной видеоконференции.

calendarUpdate

Эта операция изменяет событие в Календаре с использованием объекта iCalendar типа reply. Этот элемент данных указывает, принял или отвергнул данный конкретный приглашённый приглашение на встречу.

Атрибуты:

• calendar

  имя Календаря.

Тело:

Объект iCalendar типа reply.

calendarForward

Эта операция создаёт копию события в Календаре и отправляет её в виде приглашения.

Атрибуты:

• calendar

  имя Календаря.

• UID

  UID Ссобытия.

• Тело:

Один или более элементов To с адресами получателей.

calendarAccept

Эта операция помещает событие в Календарь и отправляет положительный ответ организатору События. Существующие элементы данных, имеющие тот же UID, удаляются.

Атрибуты:

• calendar

  имя Календаря.

• PARTSTAT

  статус принятия: ACCEPTED, TENTATIVE, IN-PROCESS (только для Заданий), COMPLETED (только для Заданий).

• sendReply

  если этим необязательным атрибутом является no, то организатору не отправляется сообщение с ответом.

• folder

  необязательное имя Представления папки из которого было зачитано обрабатываемое приглашение. При обработке приглашений из папки другого аккаунта этот параметр должен указывать на эту папку для того, чтобы для календарной операции использовался Календарь по умолчанию владельца папки в соответствии с правом Делегата.

• proposedTimeStart

  необязательный атрибут с новым временем начала события. Если он указан, то организатору направляется календарный ответ типа COUNTER.

Тело:

• Объект iCalendar для помещения в выбранный Календарь;
• необязательные элементы MIME и/или copyMIME для добавления (аналогично элементам, используемым в операции messageAppend);
• необязательный объект replyComment, содержащий текстовое тело - комментарий, включаемый в сообщение ответа.

Если событие помещено успешно, тот организатору отправляется сообщение iCalendar типа reply. Ответы не отправляются для Событий текущего пользователя (если он является приглашённым на встречу с параметром RSVP=FALSE) или если атрибут запроса sendReply имеет значение no.

calendarDecline

Эта операция используется для отклонения приглашений и контр-предложений, а также для отправки ответа организатору события или участнику, чьё контр-предложение было отклонено.

Атрибуты:

• calendar

  имя Календаря. Этот параметр является необязательным.
  Если он указан, то объекты с таким же UID удаляются из этого Календаря.
  Если объект имеет атрибут recurrenceId, тогда только исключение удаляется из Календаря.

• sendReply

  если этим необязательным атрибутом является no, то организатору или участнику, который сделал контр-предложение, не отправляется сообщение с ответом. По умолчанию — yes.

• folder

  необязательное имя Представления папки из которого было зачитано обрабатываемое приглашение. При обработке приглашений из папки другого аккаунта этот параметр должен указывать на эту папку для того, чтобы для календарной операции использовался Календарь по умолчанию владельца папки в соответствии с правом Делегата.

• attendeeEmail

  Email участника, чьё контр-предложение отклоняется. Используется только для обработки DECLINECOUNTER.

Тело:

• Отклоняемый объект iCalendar.
• необязательный объект replyComment, содержащий текстовое тело - комментарий, включаемый в сообщение ответа.

Используйте эту операцию, если пользователь решает не присутствовать на встрече, хранящейся как опубликованное в Календаре событие (если текущий пользователь является организатором встречи, используйте вместо этого операцию calendarCancel).
Укажите само опубликованное событие и атрибут calendar для удаления события из Календаря.
Операция отправляет отрицательный ответ организатору этого события (за исключением случаев, когда атрибут sendReply установлен в значение no).

Используйте эту операцию, если пользователь открывает объект с приглашением (во входящем сообщении электронной почты) и решает отклонить это приглашение.
Укажите объект с приглашением и не указывайте никаких атрибутов calendar.
Операция отправляет отрицательный ответ организатору этого события (за исключением случаев, когда атрибут sendReply установлен в значение no).

Используйте эту операцию, если пользователь открывает объект с запросом на отмену (во входящем сообщении электронной почты) и решает удалить отменённое событие из Календаря.
Укажите элемент данных с запросом на отмену и атрибут calendar (обычно - имя Главного Календаря), чтобы удалить соответствующие элементы данных из этого календаря.
Операция не отправляет никакого сообщения с ответом.

Если указанный элемент данных является запросом, то операция отправляет отрицательный ответ организатору этого события.
Если указанный элемент данных является запросом на отмену, то операция не отправляет сообщение с ответом организатору этого события; укажите атрибут calendar для удаления соответствующего события из Календаря.

Используйте эту операцию, если пользователь решает отклонить предложенное ему альтернативное время встречи участником. Отклонение контр-предложения обрабатывается, используя атрибут attendeeEmail. Если sendReply="no", то контр-предложение удаляется только из календаря организатора. Если sendReply не задано (или yes), то участнику отправляется уведомление.

Дополнительные пояснения:

Контр-предложения, о которых идет речь в данной операции, соответствуют стандарту, описанному в RFC 5546 (iTIP, iCalendar). В этой спецификации контр-предложение представляет собой ответ участника, предлагающего новое время для события. Операция отклонения контр-предложения используется для того, чтобы отклонить предложенное изменение времени встречи, удаляя его из календаря или отправляя уведомление участнику.

calendarImport

Эта операция разбирает загруженный файл, в котором должны содержаться объекты iCalendar/vCalendar. Получившиеся события копируются в Календарь. Существующие элементы данных, имеющие тот же UID, удаляются.

Атрибуты:

• calendar

  имя Календаря.

• uploadID

  строка, идентифицирующая файл в "наборе загруженных файлов".

freeBusyRead

Эта операция получает информацию о календарной Занятости для указанного Пользователя.

Атрибуты:

• userName

  имя требуемого Пользователя. Если этот атрибут не указан, то запрашивается информация о календарной Занятости текущего Пользователя.

• timeFrom, timeTill

  начало и конец временного интервала (значения времени должны быть указаны для выбранного часового пояса). Сервер отправляет сообщение с данными freeBusyData.

• excludedUID

  UID события, исключаемого из расчёта занятости, чтобы избежать конфликта самого с собой при редактировании или переносе.

calendarGetEventUID

Эта операция запрашивает у Сервера UID сообщения с заданным UID записи о Событии (iCalendar).

Атрибуты:

• calendar

  имя Календаря

• itemUID

  строка с UID записи о Событии (iCalendar)

Сервер отправляет сообщение с данными calendarEventUID.

Сервер присылает следующие сообщения с данными:

events

Это синхронное сообщение с данными отправляется, когда Сервер обрабатывает запрос findEvents.

Атрибуты:

• calendar, timeFrom, timeTill, skip

  аналогично атрибутам запроса findEvents.

• items

  общее число найденных Событий.

• Тело:

набор элементов event для каждого найденного События.

Атрибуты:

• UID

  число: UID События.

• itemUID

  строка с UID События (iCalendar).

• timeFrom

  время начала этого События (в выбранном часовом поясе). Этот атрибут не включается для Событий "на весь день", когда не выбран режим byAlarm.

• dateFrom

  дата начала этого События (в выбранном часовом поясе). Этот атрибут включается только для Событий "на весь день", и только когда не выбран режим byAlarm.

• duration

  продолжительность События (в секундах).

• alarmTime

  этот атрибут включается только если запрос содержал атрибут byAlarm. Значение атрибута указывает на время (в выбранном часовом поясе), когда должно произойти Уведомление о Событии.

• busyStatus

  строка со статусом занятости для События(BUSY, TENTATIVE, UNAVAILABLE, FREE).

• partstat

строка со статусом участия запрашивающего пользователя (NEEDS-ACTION, ACCEPTED, DECLINED, TENTATIVE).

• organizer

  этот атрибут присутствует и имеет значение yes если текущий пользователь является организатором События.

• recurrence

  этот атрибут присутствует и имеет значение yes если Событие является повторяющимся.

• recurrenceId

  этот атрибут присутствует если найденное Событие является исключением повторяющегося события. Значением атрибута является отметка времени, идентифицирующая это исключение.

• attendees

  этот атрибут присутствует или у События есть участники. Значением атрибута является число участников.

• location

  этот атрибут присутствует, если у События есть атрибут Location. Значением атрибута является значение элемента Location (возможно - сокращённое).

• priority

  этот атрибут присутствует если для События установлен приоритет.

• class

  опциональный атрибут, содержащий строку с классом приватности события (PUBLIC, PRIVATE, CONFIDENTIAL).

• Тело:

  Поля События: summary

tasks

Это синхронное сообщение с данными отправляется, когда Сервер обрабатывает запрос findTasks.

Атрибуты:

• calendar, timeFrom, timeTill, skip

  аналогично атрибутам запроса findTasks.

• items

  общее число найденных Заданий.

Тело:

набор элементов task для каждого найденного Задания.

• Атрибуты:

• UID

  UID Задания (число).

• itemUID

  строка с UID объекта Задания (iCalendar).

• timeFrom

  время начала этого Задания (в выбранном часовом поясе).

• due

  ожидаемое время исполнения этого Задания (в выбранном часовом поясе).

• percent-complete

  уровень готовности Задания; число, обычно в диапазоне от 0 до 100.

• alarmTime

  этот атрибут включается только если запрос содержал атрибут byAlarm. Значение атрибута указывает на время (в выбранном часовом поясе), когда должно произойти Уведомление о Задании.

• organizer

  этот атрибут присутствует и имеет значение yes если текущий пользователь является организатором Задания.

• recurrence

  этот атрибут присутствует и имеет значение yes если Задание является повторяющимся.

• recurrenceId

  этот атрибут присутствует если найденное Задание является исключением повторяющегося задания. Значением атрибута является отметка времени, идентифицирующая это исключение.

• attendees

  этот атрибут присутствует или у Задания есть исполнители. Значением атрибута является число исполнителей.

• location

  этот атрибут присутствует, если у Задания есть атрибут Location. Значением атрибута является значение элемента Location (возможно - сокращённое).

• priority

  этот атрибут присутствует если для Задания установлен приоритет.

• Тело:

  Поля Задания: summary

calendarReport

Эти сообщения отправляются при изменении данных Календаря.

Атрибуты:

• calendar

  имя Календаря.

• mode

  в этом необязательном атрибуте задаётся тип уведомления.

  • Если значением атрибута является notify, то некоторые сообщения были добавлены в Календарь, изменены или удалены из Календаря.
    Ожидается, что в ответ клиент направит запрос findEvents для этого Календаря.

После того, как Сервер отправляет "уведомительное" сообщение calendarReport Клиенту, Сервер может не отправлять дальнейшие "уведомительные" сообщения для этого Календаря до тех пор, пока клиент не выполнит для этого Календаря операцию findEvents.

calendarMessage

Это синхронное сообщение с данными отправляется, когда Сервер обрабатывает запрос calendarRead.
Это сообщение аналогично сообщению folderMessage, но вместо атрибута folder в нём содержится атрибут calendar с именем Календаря.

calendarItem

Это синхронное сообщение с данными отправляется, когда Сервер обрабатывает запрос calendarReadItem.

Атрибуты:

• calendar, UID

  копия этого же атрибута из запроса calendarReadItem.

• Тело:

XML представление атрибутов объекта (vevent, vtodo).

freeBusyData

Это синхронное сообщение данных отправляется, когда Сервер обрабатывает запрос freeBusyRead.

Атрибуты:

• userName

  копия этого же атрибута из запроса freeBusyRead.

• Тело:

объект vfreebusy, содержащий набор элементов freebusy. Все возвращаемые значения времени используют Часовой Пояс, выбранный для текущего пользователя.

После того, как Сервер отправляет "уведомительное" сообщение calendarReport Клиенту, Сервер может не отправлять дальнейшие "уведомительные" сообщения для этого Календаря до тех пор, пока клиент не выполнит для этого Календаря операцию findEvents.

calendarEventUID

Это синхронное сообщение с данными отправляется, когда Сервер обрабатывает запрос calendarGetEventUID.

Атрибуты:

• calendar, itemUID

  копия этих же атрибутов из запроса calendarGetEventUID

• UID

  UID сообщения (числовой).

Пример:

C:<calendarGetEventUID calendar="Calendar" id="A001" itemUID="869760485.2.user" />
S:<calendarEventUID id="A001" calendar="Calendar" itemUID="869760485.2.user" UID="2"/>

Сигналы

Клиент должен использовать операцию "bind" для того, чтобы начать получать сигналы, направляемые аутентифицированному пользователю.

Клиент может обслуживать одну или несколько одновременных коммуникационных сессий ("звонков"). Каждый звонок идентифицируется по его атрибуту callLeg. Атрибут callLeg присутствует во всех запросах клиента и сообщениях сервера, относящихся к звонку. Все звонки независимы друг от друга.

Для каждого звонка клиент должен уметь создать один или несколько "медиа-объектов", которые фактически реализуют медиа сессии заданного типа (аудио, видео и т.д.). Описатели медиа данных ("объекты SDP") - это элементы данных (в виде текста или XML), которыми клиент обменивается со своими "медиа-объектами".
Как минимум, с каждым медиа-объектом должны быть возможны следующие операции:

• получить SDP "предложения" от медиа-объекта, а потом передать ему SDP "ответа", который описывает медиа-объект абонента; или
• передать SDP "предложения", описывающим медиа-объект абонента, а потом получить SDP "ответа".

Если перепосылка SDP с "предложением" уже активному медиа-объекту невозможна, то должен быть создан новый объект, и "предложение" должно быть отправлено ему. Если от нового медиа-объекта был успешно получен SDP с "ответом", то старый медиа-объект должен быть уничтожен.

Если получение SDP с "предложением" от уже активного медиа-объекта невозможно, то должен быть создан новый объект, и "предложение" должно быть получено от него. Когда SDP "ответа" получен и передан новому медиа-объекту, старый медиа-объект должен быть уничтожен.

медиа-объект поддерживает "расщепление" (forking), если от него возможно получить единственное SDP "предложение", а потом передать ему несколько SDP "ответов", установив таким образом несколько коммуникационных каналов.

Описатель SDP

Большинство описанных в этом разделе сообщений и запросов может содержать SDP в виде объекта XML.
Описатель SDP может быть передан в виде представления XML или как элемент XML sdpText с данными SDP в оригинальном текстовом формате.
Операция signalBind определяет формат, который будет использоваться Сервером

signalBind

Эта операция позволяет текущей сессии XIMSS получать сигналы, направляемые аутентифицированному пользователю.

Атрибуты:

• clientID

  необязательный параметр, задающий имя сессии. Если он не указан, Сервер создаст уникальный идентификатор.

• mode

  если этот атрибут задан и его значение - fixed, Сервер отказывает в выполнении запроса, если у Пользователя уже есть сессии с таким именем;
  если атрибут задан и его значение - kill, Сервер закрывает сессию с таким именем (если она есть).
  если атрибут не задан или имеет любое другое значение, Сервер создаёт для сессии уникальное имя, если имя в запросе уже занято другой сессией Пользователя;

• presence

  если этот необязательный атрибут задан и его значением является yes, то клиент начинает получать уведомления Ростера и Статуса Присутствия.

• readIM

  если этот необязательный атрибут существует и его значением является 1, то сообщения сервера readIM используют "расширенный" формат.

Тело (необязательно):

XML представление дескриптора SDP клиента.
Дескриптор используется для указания возможностей клиента (способность принимать аудио/видео звонки) и для определения конфигураций "дальнего NAT".

Обратите внимание

Чтобы определять "дальние NAT" конфигурации, дескриптор SDP должен содержать атрибут ip с IP адресом медиа, используемым клиентом по умолчанию (смотрите ниже).

Элемент XML sdpText может быть использован вместо элемента SDP. Элемент XML sdpText должен быть текстовым элементом, содержащим данные SDP в оригинальном текстовом формате SDP.
При использовании sdpText данные SDP в сообщениях Сервера callIncoming, callProvisioned, callConnected и callUpdated будут представляться тоже в виде sdpText.

signalUnbind

После завершения этой операции текущая сессия XIMSS не получает сигналы, направляемые аутентифицированному пользователю.

callKill

Используйте эту операцию, чтобы завершить звонок и освободить все связанные ресурсы.
Если звонок находился в состоянии "calling", то исходящий звонок прекращается.
Если звонок находился в состоянии "alerting", то входящий звонок отвергается.
Если звонок находился в состоянии "connected", то абоненту отправляется запрос на отсоединение.

Атрибуты:

• callLeg

  идентификатор звонка. После успешного завершения этой операции можно производить новые звонки с таким же идентификатором.

Исходящие звонки начинаются Клиентом с помощью запроса callStart. Клиент должен создать уникальный идентификатор для использования его в качестве значения атрибута callLeg в запросе callStart. Во всех остальных сообщениях и запросах, имеющих отношение к этому звонку, будет использоваться то же значение атрибута callLeg.
Когда начинается исходящий звонок, Сервер может прислать:

• ноль, одно или несколько сообщений callProvisioned
• ноль, одно или несколько сообщений callUpdateRequest
• ноль или одно сообщение callUpdateSolicited

Каждое из этих сообщений содержит атрибут tag, идентифицирующий "ранний диалог" (одно из "звонящих" устройств абонента).
Когда начинается исходящий звонок, Клиент может прислать:

• ноль, один или несколько запросов callUpdate для "ранних диалогов", установленных с помощью сообщений callProvisioned, callUpdateRequest, callUpdateSolicited. Для каждого запроса callUpdate Сервер присылает сообщение callUpdated.

Исходящий звонок переходит в состояние "установлен", когда Сервер присылает сообщение callConnected.
Исходящий звонок аварийно прекращается, если Сервер присылает сообщение callDisconnected.
Клиент может прекратить исходящий звонок, используя операцию callKill.

Входящие звонки начинаются с посылкой Клиенту Сервером сообщения callIncoming. Сервер создаёт уникальный идентификатор для использования его в качестве значения атрибута callLeg для сообщения callIncoming. Во всех остальных сообщениях и запросах, имеющих отношение к этому звонку, будет использоваться то же значение атрибута callLeg. Созданное Сервером для входящих звонков значение атрибута callLeg использует префикс inp, поэтому Клиент не должен использовать такой префикс для значений атрибута callLeg в исходящих звонках.
Когда принимается входящий звонок, Сервер может прислать:

• ноль, одно или несколько сообщений callUpdateRequest

Когда принимается входящий звонок, Клиент может послать:

• ноль, один или несколько запросов callProvision. Для каждого запроса callProvision Сервер присылает сообщение callUpdated.
• ноль, один или несколько запросов callUpdate. Для каждого запроса callUpdate Сервер присылает сообщение callUpdated.

Входящий звонок аварийно прекращается (отменяется), если Сервер присылает сообщение callDisconnected.
Клиент может прекратить обработку входящего звонка, отвергнув его с помощью запроса callReject или перенаправив его с помощью запроса callRedirect.
Клиент может принять входящий звонок с помощью запроса callAccept, тем самым переведя его в состояние "установлен".

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

• ноль, одно или несколько сообщений callUpdateRequest
• ноль, одно или несколько сообщений callUpdateSolicited

Когда звонок установлен, Клиент может прислать:

• ноль, один или несколько запросов callUpdate. Для каждого запроса callUpdate Сервер присылает сообщение callUpdated.

Установленный звонок прекращается, если Сервер присылает сообщение callDisconnected.
Клиент может окончить установленный звонок, послав запрос callKill.

callStart

Используйте эту операцию, чтобы начать исходящий звонок.

Атрибуты:

• callLeg

  идентификатор нового звонка. В текущей сессии XIMSS не должно быть других звонков с таким идентификатором.

• peer

  адрес электронной почты или SIP URI вызываемого абонента.

• peerName

  необязательная строка: "настоящее имя" абонента.

Тело (необязательно):
Описатель SDP.

Если запрос callStart завершается успешно, то создаётся новый объект звонка и начинается исходящий вызов.

Обратите внимание

Клиент должен быть готов обрабатывать относящиеся к новому звонку сообщения Сервера ещё до получения положительного ответа на запрос callStart.

Обратите внимание

Если вызов не заканчивается успешно (получено сообщение callDisconnected), то клиенту всё равно необходимо использовать операцию callKill, чтобы освободить ресурсы, связанные с этим звонком и сделать возможным повторное использование идентификатора звонка.

Управление Медиаданными

Вызов с SDP: Клиент создаёт медиа-объект ("немаркированный" объект).
Клиент должен настроить созданный медиа-объект для работы в режиме "только принимать".
Клиент получает от немаркированного медиа-объекта "предложение" SDP и передаёт этот объект SDP с запросом callStart Серверу.

Обратите внимание

Чтобы корректно обрабатывать вызовы "за NAT", дескриптор SDP должен содержать атрибут ip с IP адресом медиа, используемым клиентом по умолчанию.

Вызов без SDP: клиент не создаёт медиа-объект. Клиент шлёт запрос callStart без элемента SDP в теле.

По выбору, Клиент должен быть готов к созданию дополнительных медиа-объектов и поддержке "отображения", в котором каждому созданному медиа-объекту соответствует строка тега - значение атрибута tag из полученных от Сервера сообщений callProvisioned и/или callUpdateRequest.

callProvision

Используйте эту операцию, чтобы направить промежуточный отклик на входящий звонок (объект звонка создаётся, когда Сервер присылает сообщение callIncoming). Предварительный ответ на звонок информирует вызывающую сторону, что вызываемый абонент проинформирован о входящем звонке (у него "звонит телефон").

• Атрибуты:

• callLeg

  идентификатор входящего звонка.

• Тело (необязательно):

Описатель SDP.

При выполнении запроса Клиент получает сообщение callUpdated от Сервера.

Управление Медиаданными

Если Клиенту надо отправить "ранние медиаданные" (КПВ) вызывающей стороне, Клиент использует запрос callProvision с данными SDP. "Ранние медиаданные" могут быть проиграны устройством вызывающей стороны вместо обычных "гудков дозвона".
Для передачи "ранних медиаданных" Клиент должен создать немаркированный медиа-объект.
Клиент должен настроить созданный медиа-объект для работы в режиме "только передавать".

• Если сообщение callIncoming содержало SDP:

  Этот объект SDP является предложением.
  Клиент должен передать это "предложение" SDP немаркированному медиа-объекту.
  Затем Клиент должен получить от этого медиа-объекта "ответ" SDP и послать его на Сервер в теле запроса callProvision. После этого Клиент может включить проигрывание "ранних медиаданных" медиа-объектом.

• Если сообщение callIncoming не содержало SDP:

  Затем Клиент должен получить от немаркированного медиа-объекта "предложение" SDP и послать его на Сервер в теле запроса callProvision.
  В полученном Клиентом от Сервера сообщении callUpdated будет содержаться либо "ответ" SDP, либо код ошибки.
  Если получен "ответ" SDP, Клиент должен передать его немаркированному медиа-объекту и затем может включить проигрывание "ранних медиаданных".

callRedirect

Используйте эту операцию для того, чтобы перенаправить входящий вызов.

Атрибуты:

• callLeg

  идентификатор входящего звонка.

• fork

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

Тело:

один или более элементов XML To. Каждый элемент должен иметь текстовое тело, в котором указывается URI, на который необходимо перенаправить звонок.

Обратите внимание

Клиенту всё равно необходимо использовать операцию callKill, чтобы освободить ресурсы, связанные с этим вызовом и сделать возможным повторное использование идентификатора вызова.

Пример:
Перенаправление входящего вызова inp003 на user1@example.com и user2@example.com.

C:<callRedirect id="A018" callLeg="inp003" >
    <To>user1@example.com</To><To>user2@example.com</To>
  </callRedirect>
S:<response id="A018"/>

Управление Медиаданными

Клиент должен освободить все медиа-объекты, связанные с этим звонком.

callReject

Используйте эту операцию, чтобы отвергнуть входящий вызов. Вы так же можете использовать операцию callKill, но операция callReject позволяет вам указать код ошибки.

Атрибуты:

• callLeg

  идентификатор входящего звонка.

• signalCode

  числовой код (определяемый стандартами SIP), который передаётся в компонент Signal как код ошибки.
  Используйте код 486 ("Здесь занято"), чтобы просигнализировать, что это устройство "Занято" (но другие устройства, зарегистрированные на этого пользователя, будут продолжать звонить).
  Используйте код 6xx (600 - "Занято везде" или 603 - "Отклонено"), чтобы просигнализировать, что пользователь не хочет принимать этот сигнал ни на каком устройстве (все другие устройства также прекратят звонить).
  Если этот параметр не указан, то используется код 603.

  Обратите внимание

  Клиенту всё равно необходимо использовать операцию callKill, чтобы освободить ресурсы, связанные с этим вызовом и сделать возможным повторное использование идентификатора вызова.

Пример:
Отвергаем входящий вызов inp004 с кодом 603 "Declined":

C:<callReject id="A020" callLeg="inp004" signalCode="603" />
S:<response id="A020"/>

Управление Медиаданными

Клиент должен освободить все медиа-объекты, связанные с этим звонком.

callAccept

Используйте эту операцию, чтобы принять входящий звонок.

Атрибуты:

• callLeg

  идентификатор входящего звонка.

• Тело (необязательно):

Описатель SDP.

При выполнении запроса Клиент получает сообщение callUpdated от Сервера.

Управление Медиаданными

Клиент должен создать немаркированный медиа-объект, если он не был ещё создан.

• Если Клиент уже отправил запрос callProvision с данными SDP:

  Запрос callAccept не должен содержать SDP в теле, и сообщение callUpdated не будет содержать SDP.

• Если Клиент ещё не отправил запрос callProvision с данными SDP, а сообщение callIncoming содержало SDP:

  Этот объект SDP является предложением.
  Клиент должен передать это "предложение" SDP немаркированному медиа-объекту.
  Затем Клиент должен получить от этого медиа-объекта "ответ" SDP и послать его на Сервер в теле запроса callAccept.
  Когда звонок устанавливается, Клиент получает от Сервера сообщение callUpdated без SDP.

• Если Клиент ещё не отправил запрос callProvision с данными SDP, и сообщение callIncoming тоже не содержало SDP:

  Клиент должен получить от немаркированного медиа-объекта "предложение" SDP и послать его на Сервер в теле запроса callAccept.
  Клиент получит от Сервера сообщение callUpdated, которое будет содержать "ответ" SDP.
  Клиент должен передать этот "ответ" SDP немаркированному медиа-объекту.
  Клиент должен прекратить проигрывание "ранних медиаданных" "немаркированным" медиа-объектом и настроить его для работы в режиме "отправлять и принимать".

callUpdate

Используйте эту операцию, чтобы изменить звонок (изменить SDP дескриптор). Клиенту может понадобиться использовать этот запрос для постановки звонка "на удержания" или возобновления звонка, для изменения количества и типов медиа потоков (например, для добавления видео потока к аудио звонку), для переключения на другой медиа-объект и т.д.

Атрибуты:

• callLeg

  идентификатор звонка.

• tag

  необязательно: "to-tag" (идентификатор диалога/ветвления) для "раннего диалога"; должен использоваться при изменении параметров исходящего звонка.

• Тело (необязательно):

Описатель SDP.

При выполнении запроса Клиент получает сообщение callUpdated от Сервера.
В случае неудачи, сообщение callUpdated содержит атрибуты signalCode и errorText. В случае успеха сообщение callUpdated не содержит этих атрибутов.

Управление Медиаданными

Если Клиенту не требуется изменять дескриптор SDP, запрос callUpdate можно послать без SDP в теле. Сервер пришлёт сообщение callUpdated тоже без SDP.

Для изменения SDP Клиент должен получить от немаркированного медиа-объекта новое "предложение" SDP. Или же, Клиент должен создать новый медиа-объект и получить от него "предложение" SDP. Это "предложение" должно быть отправлено в теле запроса callUpdate.
Если сообщение callUpdated не содержит атрибут errorText, оно содержит "ответ" SDP, и Клиент должен передать его медиа-объекту. Если это - новый медиа-объект, то старый "немаркированный" медиа-объект должен быть удалён, а новый должен стать текущим "немаркированным" медиа-объектом.
В случае неудачи, сообщение callUpdated содержит атрибут errorText. В этом случае немаркированный медиа-объект должен быть возвращён в предыдущее состояние. Если для получения "предложения" SDP был создан новый медиа-объект, то он должен быть удалён.

callTransfer

Используйте эту операцию, чтобы передать присоединённого абонента другому абоненту.

Атрибуты:

• callLeg

  идентификатор звонка.

• peer

  адрес электронной почты или SIP URI, на которые необходимо передать звонок. Используйте этот атрибут, чтобы начать "несопровождаемый перевод".

• otherLeg

  идентификатор звонка. Он должен указывать на некоторый другой "звонок" в этой сессии. Оба звонка должны быть в установленном состоянии. Используйте этот атрибут для завершения операции "сопровождаемого перевода". Удалённый абонент звонка "callLeg" соединяется с удалённым абонентом звонка "otherLeg".

Если атрибут otherLeg указан, то атрибут peer игнорируется.

Если операция перевода звонка завершилась успешно, то звонок "callLeg" отсоединяется (клиенту отправляется сообщение callDisconnected). В дополнении к этому, в операции "сопровождаемого перевода" клиент также получает сообщение callDisconnected и для звонка "otherLeg".

Если операция перевода звонка завершилась неудачей, то клиент получает сообщение callOpFailed.

callUpdateAccept

Используйте эту операцию для того, чтобы принять запрос об изменении параметров SDP звонка.

Атрибуты:

• callLeg

  идентификатор звонка.

• Тело (необязательно):

Описатель SDP.

Клиент должен отправить такой запрос при получении сообщений callUpdateRequest, callProvisioned и callConnected. Дополнительную информацию смотрите в описании этих сообщений.

callUpdateReject

Используйте эту операцию для того, чтобы отвергнуть запрос об изменении параметров SDP звонка.

Атрибуты:

• callLeg

  идентификатор звонка.

• signalCode

  числовой код (определяемый стандартами SIP), который передаётся в компонент Signal как код ошибки.
  Если этот атрибут отсутствует, то используется код 488 ("Not Acceptable Here").

Тело:

отсутствуетКлиент должен послать такой запрос вместо запроса callUpdateAccept в случаях, когда модификация параметров SDP звонка оказалась невозможной.
Дополнительную информацию смотрите в описании callUpdateAccept.

callSendDTMF

Используйте эту операцию для отправки DTMF сигнала через канал сигнализации.

Атрибуты:

• callLeg

  идентификатор звонка.

• Тело:

строка с DTMF кодом, который необходимо отправить (10 для '*', 11 для '#').

Если операция заканчивается успешно, то сервер возвращает сообщение callOpCompleted.

Если операция не заканчивается успешно, то сервер возвращает сообщение callOpFailed.

callSendInfo

Используйте эту операцию для того, чтобы передать абоненту сигнал INFO.

Атрибуты:

• callLeg

  идентификатор звонка.

  Тело:

  элемент MIME XML:

  Атрибуты:

  • type

    Content-Type содержимого INFO.

  • subtype

    Подтип содержимого INFO (необязательно).

    Тело:

    строка с данными содержимого INFO.

Если операция заканчивается успешно, то сервер возвращает сообщение callOpCompleted.

Если операция заканчивается неуспешно, то сервер возвращает сообщение callOpFailed.

makeCall

Используйте эту операцию, чтобы совершить звонок с использованием любого зарегистрированного устройства или клиента. Сервер инициирует вызов аутентифицированному Пользователю ("самовызов"), что приводит к тому, что все зарегистрированные устройства Пользователя начинают звонить. Когда любое устройство отвечает на звонок, то это устройство получает указание совершить звонок на указанный адрес (или телефонный номер).

Атрибуты:

• peer

  адрес электронной почты или SIP URI вызываемого абонента.

• callerParams

  необязательный атрибут, содержащий параметры SIP URI для "самовызова".

Операция выполняется, как только запускается задача CG/PL, реализующая эту функцию. Асинхронные сообщения makeCallReport присылаются при изменении статуса задачи. Сразу по выполнении попытки дозвона присылается пустое сообщение makeCallReport.

Сервер может отправлять следующие сообщения с данными:

callDisconnected

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

Атрибуты:

• callLeg

  идентификатор звонка.

• signalCode

  в этом необязательном атрибуте указывается числовой код ошибки.

• errorText

  в этом необязательном атрибуте указывается причина разъединения звонка.

  Обратите внимание

  Клиенту всё равно необходимо использовать операцию callKill, чтобы освободить ресурсы, связанные с этим вызовом, и сделать возможным повторное использование идентификатора вызова.

Управление Медиаданными

Клиент должен освободить все медиа-объекты, связанные с этим звонком.

callProvisioned

Эти асинхронные сообщения данных отправляются, когда исходящий вызов находится в процессе обработки (после того, как Сервером был получен запрос callStart):

Атрибуты:

• callLeg

  идентификатор звонка.

• callId

  строка с Call-ID звонка.

• tag

  "to-tag" (идентификатор диалога/ответвления) для "раннего диалога".

• Тело (необязательно):

Описатель SDP.

В ответ Клиент должен отправить Серверу запрос callUpdateAccept или callUpdateReject.

Управление Медиаданными

• Если сообщение callProvisioned не содержало SDP:

  если со значением атрибута tag связан медиа-объект или проигрыватель "тона дозвона" (КПВ), Клиент должен игнорировать это сообщение.
  Иначе, Клиент должен создать проигрыватель "тона дозвона" (который уведомляет звонящего, что вызываемый абонент информируется о входящем звонке) и связать его со значением атрибута tag.

• Если сообщение callProvisioned содержит SDP, и создан медиа-объект, связанный со значением атрибута tag:

  Этот объект SDP является предложением.
  Клиент должен передать это "предложение" SDP соответствующему (маркированному) медиа-объекту. Затем Клиент должен получить от этого медиа-объекта "ответ" SDP и послать его на Сервер в теле запроса callUpdateAccept.

• Если сообщение callProvisioned содержит SDP, а медиа-объекта, связанного со значением атрибута tag, - нет, и запрос callStart был сделан с "предложением" SDP:

  Этот объект SDP является ответом.
  Клиент должен запомнить этот "ответ" SDP и связать его со значением атрибута tag, заменяя старый SDP, связанный с этим значением атрибута tag.
  Если "немаркированный" медиа-объект поддерживает "расщепление" (ветвление вызова), Клиент должен передать этот "ответ" SDP этому медиа-объекту; Клиент должен также убрать объект проигрывателя "тонов дозвона", связанный с этим значением атрибута tag.
  Если "немаркированный" медиа-объект не поддерживает "расщепление", Клиент должен создать объект проигрывателя "тонов дозвона" (если его ещё нет) и связать его с этим значением атрибута tag.

• Если сообщение callProvisioned содержит SDP, а медиа-объекта, связанного со значением атрибута tag, - нет, и запрос callStart был сделан без "предложения" SDP:

  Этот объект SDP является предложением.
  Клиент должен создать новый медиа-объект и связать его с этим значением атрибута tag. Если со значением атрибута tag связан медиа-объект или проигрыватель "тона дозвона" (КПВ), Клиент должен удалить его.
  Клиент должен передать это "предложение" SDP новому медиа-объекту, получить от него "ответ" SDP и послать его на Сервер в теле запроса callUpdateAccept.

Если Клиент не может обработать сообщение callProvisioned, он должен послать запрос callUpdateReject.

callConnected

Эти асинхронные сообщения данных отправляются, когда исходящий вызов (запущенный запросом callStart) выполняется успешно и звонок устанавливается:

Атрибуты:

• callLeg

  идентификатор звонка.

• callId

  строка с Call-ID звонка.

• peer

  адрес абонента, принявшего звонок.

• tag

  "to-tag" (идентификатор диалога/ответвления) для "установленного диалога".

• Тело (необязательно):

Описатель SDP.

В ответ Клиент должен отправить Серверу запрос callUpdateAccept или callUpdateReject.

Управление Медиаданными

• Если создан медиа-объект, связанный со значением атрибута tag, а сообщение callConnected не содержит SDP:

  Клиент должен удалить все другие медиа-объекты и проигрыватели "тонов дозвона". Выбранный медиа-объект становится "немаркированным".

• Если создан медиа-объект, связанный со значением атрибута tag, а сообщение callConnected содержит SDP:

  Этот объект SDP является предложением.
  Клиент должен передать это "предложение" SDP выбранному медиа-объекту. Затем Клиент должен получить от этого медиа-объекта "ответ" SDP и послать его на Сервер в теле запроса callUpdateAccept.
  Клиент должен удалить все другие медиа-объекты и проигрыватели "тонов дозвона". Выбранный медиа-объект становится "немаркированным".

• Если связанного со значением атрибута tag медиа-объекта нет, запрос callStart содержал "предложение" SDP, и сообщение callConnected содержит SDP:

  Этот объект SDP является ответом.
  Клиент должен передать этот "ответ" SDP немаркированному медиа-объекту. Если медиа-объект поддерживает "расщепление" (ветвление вызова) и ему был передан некоторый "ответ" SDP, Клиент должен отключить в этом медиа-объекте все другие коммуникации.
  Клиент должен удалить все другие маркированные медиа-объекты и проигрыватели "тонов дозвона".

• Если связанного со значением атрибута tag медиа-объекта нет, запрос callStart содержал "предложение" SDP, а сообщение callConnected не содержит SDP:

  Этот объект SDP является ответом.
  Если медиа-объект поддерживает "расщепление" (ветвление вызова), то ему был передан некоторый "ответ" SDP, связанный с этим значением атрибута tag. Клиент должен отключить в этом медиа-объекте все другие коммуникации.
  Если медиа-объект не поддерживает "расщепление" (ветвление вызова), то ему был передан некоторый "ответ" SDP, полученный с сообщением callProvisioned и связанный с этим значением атрибута tag, - его надо запомнить. Клиент должен передать этот запомненный "ответ" SDP немаркированному медиа-объекту.
  Клиент должен удалить все другие маркированные медиа-объекты и проигрыватели "тонов дозвона".

• Если связанного со значением атрибута tag медиа-объекта нет, запрос callStart не содержал "предложение" SDP:

  Сообщение callConnected должно содержать объект SDP, и этот объект SDP является предложением.
  Клиент должен создать новый медиа-объект и передать это "предложение" SDP этому медиа-объекту. Затем Клиент должен получить от этого медиа-объекта "ответ" SDP и послать его на Сервер в теле запроса callUpdateAccept.
  Клиент должен удалить все другие медиа-объекты и проигрыватели "тонов дозвона". Созданный медиа-объект становится "немаркированным".

"Немаркированный" медиа-объект (единственный оставшийся) должен быть настроен для работы в режиме "отправлять и получать".

callIncoming

Эти сообщения отправляются при получении новых входящих звонков (для получения входящих звонков вам необходимо использовать операцию signalBind):

Атрибуты:

• callLeg

  идентификатор звонка. Сервер самостоятельно формирует эти идентификаторы.

• peer

  адрес электронной почты удалённого абонента.

• peerName

  необязательно; настоящее имя удалённого абонента.

• callId

  строка с Call-ID звонка.

• transferredBy

  необязательно: адрес участника, который перевёл этот звонок.

• Тело (необязательно):

Описатель SDP.

Управление Медиаданными

Клиент может создать "немаркированный" медиа-объект немедленно или создать его перед посылкой запросов callProvision или callAccept.

• Если сообщение callIncoming содержало SDP:

  Этот объект SDP является предложением.
  Клиент должен передать это "предложение" SDP немаркированному медиа-объекту.

callUpdateRequest

Эти асинхронные сообщения присылаются, когда удалённый абонент пытается изменить параметры звонка (например, SDP).

Атрибуты:

• callLeg

  идентификатор звонка.

• tag

  "to-tag" (идентификатор диалога/ответвления) для "раннего диалога".

• Тело (необязательно):

Описатель SDP.

В ответ Клиент должен отправить Серверу запрос callUpdateAccept или callUpdateReject.

Управление Медиаданными

• Если сообщение callUpdateRequest не содержало SDP, то Клиент может его игнорировать.

• Если сообщение callUpdateRequest содержало SDP:

  Этот объект SDP является предложением.
  Если звонок исходящий, то Клиент должен удалить все проигрыватели "тонов дозвона", связанные с этой меткой.
  Клиент должен найти медиа-объект, связанный с этим значением атрибута tag (или создать новый медиа-объект, если связанный найти не удалось).
  Если атрибут tag не был задан, то должен использоваться "немаркированный" медиа-объект.
  "Предложение" SDP из сообщения callUpdateRequest должно быть передано выбранному медиа-объекту.
  Клиент должен получить от этого медиа-объекта "ответ" SDP и послать его на Сервер в теле запроса callUpdateAccept.
  Если Клиент не может принять новое "предложение" SDP, он должен проинформировать об этом Сервер, послав ему запрос callUpdateReject.

callUpdated

Эти асинхронные сообщения отправляются, когда существующий звонок изменяется (помещается на удержание, переключается на другого удалённого участника и т.д.).

Атрибуты:

• callLeg

  идентификатор звонка.

• peer

  необязательно; адрес электронной почты удалённого участника. Он присылается, когда звонок был переведён.

• peerName

  необязательно; настоящее имя удалённого абонента.

• signalCode

  в этом необязательном атрибуте указывается числовой код ошибки.

• errorText

  необязательно; текст сообщения об ошибке.

• Тело (необязательно):

  Описатель SDP. Сообщение присылается в ответ на запросы callUpdate, callProvision, callAccept. Дополнительную информацию смотрите в описании этих сообщений.

В случае неудачи, в сообщении содержатся атрибуты signalCode и errorText.
В случае успеха, атрибуты signalCode и errorText отсутствуют, а Описатель SDP может быть включён в тело сообщения.

callUpdateSolicited

Эти асинхронные сообщения присылаются, когда удалённый абонент пытается изменить параметры звонка (например, SDP), но сам ищет предложения.

Атрибуты:

• callLeg

  идентификатор звонка.

• tag

  "to-tag" (идентификатор диалога/ответвления) для "раннего диалога".

• Тело (необязательно):

  Описатель SDP. Сервер присылает такие сообщения только для установленных звонков или для исходящих звонков в процессе установления.

Управление Медиаданными

Клиент должен выполнить запрос callUpdate с новым "предложением" SDP.

Если Клиент не может выполнить запрос callUpdate (например, не может создать новый медиа-объект), он должен послать запрос callUpdateReject.

Для исходящего звонка в процессе установления Клиент должен создать "маркированный" медиа-объект, получить от него "предложение" SDP и послать его с запросом callUpdate.

callOpCompleted

Эти сообщения отправляются, если операции, совершаемые во время звонка (такие как callUpdate, callSendDTMF, callSendInfo) были выполнены.

Атрибуты:

• callLeg

  идентификатор звонка.

• callOpFailed

  Эти сообщения отправляются, если операции, совершаемые во время звонка (такие как callUpdate, callSendDTMF, callSendInfo) не были выполнены.

  Атрибуты:

  • callLeg

    идентификатор звонка.

  • signalCode

    числовой код ошибки.

  • errorText

    текст сообщения об ошибке.

callDTMF

Эти сообщения отправляются при получении сигнала DTMF через канал сигнализации.

Атрибуты:

• callLeg

  идентификатор звонка.

• Тело:

Строка с полученным числовым DTMF кодом.

callTransferred

Эти асинхронные сообщения присылаются, когда удалённый абонент перевёл звонок на другого абонента.

Атрибуты:

• callLeg

  идентификатор звонка.

• peer

  адрес нового абонента.

• peerName

  необязательно; настоящее имя нового абонента.

• callId

  строка с Call-ID звонка; при переводе звонка это параметр обычно меняется.

• mode

  код сценария перевода звонка (информация для отладки).

• tag

  идентификатор конечного устройства (информация для отладки).

  Тело:

  Пустое.

callInfo

Эти асинхронные сообщения присылаются при получении запросов INFO:

Атрибуты:

• callLeg

  идентификатор звонка.

• Тело:

аналогично операции callSendInfo.

makeCallReport

Эти асинхронные сообщения данных присылаются при использовании операции makeCall.

Тело:

Строка, содержащая текущей статус операции. Сообщение содержит пустое тело при завершении операции.

Пример Входящий-01. Сессия входящего звонка с начальным SDP. Клиент не шлёт вызывающей стороне никаких "тонов дозвона".

Клиент получает сообщение `callIncoming` с созданным Сервером атрибутом `callLeg`.
S:<callIncoming id="A001" callLeg="inp01" peer="user@domain" >SDP:X(offer)</callIncoming>

Клиент начинает подзывать пользователя (Клиент начинает "звонить").
Клиент информирует вызывающую сторону, что вызываемый абонент проинформирован о входящем звонке:
C:<callProvision id="A001" callLeg="inp01"/>
S:<response id="A001"/>

Пользователь решает принять звонок этим Клиентом.
Клиент создаёт немаркированный медиа-объект A, и передаёт ему полученный SDP:X(offer) ("предложение" SDP) .
Клиент получает "ответ" SDP от медиа-объекта A, и шлёт его на Сервер, принимая звонок:
C:<callAccept id="A002" callLeg="inp01">SDP:A(answer)</callAccept>
S:<response id="A002"/>
Сервер присылает сообщение `callUpdated`:
S:<callUpdated callLeg="inp01"/>
Обратите внимание: сообщение `callUpdated` прийти до сообщения `response` для запроса `callAccept`.

Клиент прекращает "звонить".
Звонок установлен, медиа-объект A настроен для работы в режиме "отправлять и получать", начался обмен медиаданными.

S:<callDisconnected callLeg="inp01" />
Звонок завершается, Клиент удаляет "немаркированный" медиа-объект A.

Клиент освобождает ресурсы Сервера, занятые в звонке:
C:<callKill id="A003" callLeg="inp01"/>
S:<response id="A003"/>

Пример Входящий-02. Сессия входящего звонка без начального SDP. Клиент не шлёт вызывающей стороне никаких "тонов дозвона".

Клиент получает сообщение `callIncoming` с созданным Сервером атрибутом `callLeg`.
S:<callIncoming id="A001" callLeg="inp01" peer="user@domain" />

Клиент начинает подзывать пользователя (Клиент начинает "звонить").
Клиент информирует вызывающую сторону, что вызываемый абонент проинформирован о входящем звонке:
C:<callProvision id="A001" callLeg="inp01"/>
S:<response id="A001"/>

Пользователь решает принять звонок этим Клиентом.
Клиент создаёт немаркированный медиа-объект A, и получает от него "предложение" SDP: SDP:A(offer).
Клиент отправляет это SDP на Сервер, принимая звонок:
C:<callAccept id="A002" callLeg="inp01">SDP:A(offer)</callAccept>
S:<response id="A002"/>
Сервер присылает сообщение `callUpdated` с "ответом" SDP:
S:<callUpdated callLeg="inp01"/>SDP:X(answer)</callUpdated>
Обратите внимание: сообщение `callUpdated` прийти до сообщения `response` для запроса `callAccept`.

Клиент прекращает "звонить".
Клиент передаёт полученный "ответ" SDP медиа-объекту A.
Звонок установлен, медиа-объект A настроен для работы в режиме "отправлять и получать", начался обмен медиаданными.

S:<callDisconnected callLeg="inp01" />
Звонок завершается, Клиент удаляет "немаркированный" медиа-объект A.

Клиент освобождает ресурсы Сервера, занятые в звонке:
C:<callKill id="A003" callLeg="inp01"/>
S:<response id="A003"/>

Пример Входящий-03. Сессия входящего звонка с начальным SDP. Клиент не шлёт вызывающей стороне никаких "тонов дозвона". Попытка дозвона остановлена вызывающей стороной (или звонок был принят другим клиентом).

Клиент получает сообщение `callIncoming` с созданным Сервером атрибутом `callLeg`.
S:<callIncoming id="A001" callLeg="inp01" peer="user@domain" >SDP:X(offer)</callIncoming>

Клиент начинает подзывать пользователя (Клиент начинает "звонить").
Клиент информирует вызывающую сторону, что вызываемый абонент проинформирован о входящем звонке:
C:<callProvision id="A001" callLeg="inp01"/>
S:<response id="A001"/>

Входящий звонок отменяется:
S:<callDisconnected callLeg="inp01" />
Звонок прекращается (Для этого клиента он - "пропущен"), Клиент прекращает "звонить".

Клиент освобождает ресурсы Сервера, занятые в звонке:
C:<callKill id="A002" callLeg="inp01"/>
S:<response id="A002"/>

Пример Входящий-04. Сессия входящего звонка с начальным SDP. Клиент не шлёт вызывающей стороне никаких "тонов дозвона". Звонок отвергнут пользователем.

Клиент получает сообщение `callIncoming` с созданным Сервером атрибутом `callLeg`.
S:<callIncoming id="A001" callLeg="inp01" peer="user@domain" >SDP:X(offer)</callIncoming>

Клиент начинает подзывать пользователя (Клиент начинает "звонить").
Клиент информирует вызывающую сторону, что вызываемый абонент проинформирован о входящем звонке:
C:<callProvision id="A001" callLeg="inp01"/>
S:<response id="A001"/>

Входящий звонок отвергается:
S:<callReject id="A002" callLeg="inp01" signalCode="603" />
S:<response id="A002"/>
Звонок завершается, Клиент прекращает "звонить".

Клиент освобождает ресурсы Сервера, занятые в звонке:
C:<callKill id="A003" callLeg="inp01"/>
S:<response id="A003"/>

Пример Входящий-05. Сессия входящего звонка с начальным SDP. Клиент не шлёт вызывающей стороне никаких "тонов дозвона". Приложение перенаправляет звонок на приложение voicemail.

Клиент получает сообщение `callIncoming` с созданным Сервером атрибутом `callLeg`.
S:<callIncoming id="A001" callLeg="inp01" peer="user@domain" >SDP:X(offer)</callIncoming>

Клиент начинает подзывать пользователя (Клиент начинает "звонить").
Клиент информирует вызывающую сторону, что вызываемый абонент проинформирован о входящем звонке:
C:<callProvision id="A001" callLeg="inp01"/>
S:<response id="A001"/>

Входящий звонок перенаправляется:
S:<callRedirect id="A002" callLeg="inp01"><To>#voicemail</To></callRedirect>
S:<response id="A002"/>
Звонок завершается, Клиент прекращает "звонить".

Клиент освобождает ресурсы Сервера, занятые в звонке:
C:<callKill id="A003" callLeg="inp01"/>
S:<response id="A003"/>

Пример Исходящий-01. Сессия исходящего звонка с начальным SDP.

Клиент создаёт медиа-объект A и использует его как "немаркированный" медиа-объект для нового звонка.
Клиент получает "предложение" SDP от этого объекта: SDP:A(offer)
C:<callStart id="A001" callLeg="c1" peer="user@domain">SDP:A(offer)</callStart>
S:<response id="A001"/>

S:<callProvisioned callLeg="c1" tag="device1"/>
Клиент создаёт проигрыватель "тонов дозвона", чтобы дать понять пользователю, что происходит вызов абонента.
C:<callUpdateAccept id="A002" callLeg="c1"/>
S:<response id="A002"/>

S:<callProvisioned callLeg="c1" tag="device1"/>
У Клиента уже есть проигрыватель "тонов дозвона" для этого устройства (тега), поэтому дополнительные операции с медиа не нужны.
C:<callUpdateAccept id="A003" callLeg="c1"/>
S:<response id="A003"/>

S:<callConnected callLeg="c1" tag="device1">SDP:X(answer)</callConnected>
Клиент удаляет проигрыватель "тонов дозвона" и передаёт полученный дескриптор SDP:X(answer) (это - "ответ" SDP) "немаркированному" медиа-объекту A. Звонок установился, медиа-объект A настроен работать в режиме "передавать и принимать", начался обмен медиа данными.
C:<callUpdateAccept id="A004" callLeg="c1"/>
S:<response id="A004"/>

S:<callDisconnected callLeg="c1" />
Звонок завершается, Клиент удаляет "немаркированный" медиа-объект A.

Клиент также освобождает ресурсы Сервера, занятые в звонке:
C:<callKill id="A005" callLeg="c1"/>
S:<response id="A005"/>

Пример Исходящий-02. Сессия исходящего звонка с начальным SDP, несколько устройств на принимающей стороне. медиа-объект не поддерживает "расщепление". Клиент не поддерживает расширенные сообщения Сервера для исходящих звонков.

Клиент создаёт медиа-объект A и использует его как "немаркированный" медиа-объект для нового звонка.
Клиент получает "предложение" SDP от этого объекта: SDP:A(offer)
C:<callStart id="A001" callLeg="c1" peer="user@domain">SDP:A(offer)</callStart>
S:<response id="A001"/>

S:<callProvisioned callLeg="c1" tag="device1"/>
Клиент создаёт проигрыватель "тонов дозвона", чтобы дать понять пользователю, что происходит вызов абонента.
C:<callUpdateAccept id="A002" callLeg="c1"/>
S:<response id="A002"/>

S:<callProvisioned callLeg="c1" tag="device2"/>
Клиент создаёт ещё один проигрыватель "тонов дозвона", чтобы пользователь знал о факте дозвона. Оба проигрывателя издают тоны дозвона (КПВ).
C:<callUpdateAccept id="A003" callLeg="c1"/>
S:<response id="A003"/>

S:<callProvisioned callLeg="c1" tag="device1">SDP:X(answer1)</callProvisioned>
Клиент сохраняет полученный SDP:X(answer1) и связывает его с тегом "device1". Изменений в медиа нет, оба проигрывателя издают тоны дозвона (КПВ).
C:<callUpdateAccept id="A004" callLeg="c1"/>
S:<response id="A004"/>

S:<callProvisioned callLeg="c1" tag="device1">SDP:X(answer2)</callProvisioned>
Клиент сохраняет полученный SDP:X(answer2) и связывает его с тегом "device1". Он заменяет полученный ранее с этим тегом SDP:X(answer1). Изменений в медиа нет, оба проигрывателя издают тоны дозвона (КПВ).
C:<callUpdateAccept id="A005" callLeg="c1"/>
S:<response id="A005"/>

S:<callUpdateRequest callLeg="c1" tag="device3">SDP:Y(offer)</callUpdateRequest>
C:<callUpdateReject id="A006" callLeg="c1" errorText="not implemented" />
S:<response id="A006"/>

S:<callUpdateSolicited callLeg="c1" tag="device4" />
C:<callUpdateReject id="A006" callLeg="c1" errorText="not implemented" />
S:<response id="A006"/>

S:<callConnected callLeg="c1" tag="device1">SDP:X(answer3)</callConnected>
Клиент удаляет все проигрыватели "тонов дозвона" и передаёт полученный медиа дескриптор SDP:X(answer3) (это - "ответ" SDP) "немаркированному" медиа-объекту A.

Сообщение <callConnected/> вообще могло прийти без SDP:
S:<callConnected callLeg="c1" tag="device1"/>
Клиент удаляет все проигрыватели "тонов дозвона" и передаёт сохранённый медиа дескриптор SDP:X(answer2), поскольку он был последним полученным для тега "device1". Клиент передаёт медиа дескриптор SDP:X(answer2) (это - "ответ" SDP) "немаркированному" медиа-объекту A.

Звонок установился, медиа-объект A настроен работать в режиме "передавать и принимать", начался обмен медиа данными.
C:<callUpdateAccept id="A006" callLeg="c1"/>
S:<response id="A006"/>

Пользователь решает завершить звонок, Клиент завершает звонок и освобождает связанные с ним ресурсы Сервера:
S:<callKill id="A007" callLeg="c1" />
S:<response id="A007"/>
Звонок заканчивается, Клиент удаляет "немаркированный" медиа-объект A.

Пример Исходящий-03. Сессия исходящего звонка с начальным SDP, несколько устройств на принимающей стороне. медиа-объект не поддерживает "расщепление", дополнительные сообщения от вызываемых устройств.

Клиент создаёт медиа-объект A и использует его как "немаркированный" медиа-объект для нового звонка.
Клиент получает "предложение" SDP от этого объекта: SDP:A(offer)
C:<callStart id="A001" callLeg="c1" peer="user@domain">SDP:A(offer)</callStart>
S:<response id="A001"/>

S:<callProvisioned callLeg="c1" tag="device1"/>
Клиент создаёт проигрыватель "тонов дозвона", чтобы дать понять пользователю, что происходит вызов абонента.
C:<callUpdateAccept id="A002" callLeg="c1"/>
S:<response id="A002"/>

S:<callProvisioned callLeg="c1" tag="device2"/>
Клиент создаёт ещё один проигрыватель "тонов дозвона", чтобы пользователь знал о факте дозвона. Оба проигрывателя издают тоны дозвона (КПВ).
C:<callUpdateAccept id="A003" callLeg="c1"/>
S:<response id="A003"/>

S:<callProvisioned callLeg="c1" tag="device1">SDP:X(answer1)</callProvisioned>
Клиент сохраняет полученный SDP:X(answer1) и связывает его с тегом "device1". Изменений в медиа нет, оба проигрывателя издают тоны дозвона (КПВ).
C:<callUpdateAccept id="A004" callLeg="c1"/>
S:<response id="A004"/>

S:<callProvisioned callLeg="c1" tag="device1">SDP:X(answer2)</callProvisioned>
Клиент сохраняет полученный SDP:X(answer2) и связывает его с тегом "device1". Он заменяет полученный ранее с этим тегом SDP:X(answer1). Изменений в медиа нет, оба проигрывателя издают тоны дозвона (КПВ).
C:<callUpdateAccept id="A005" callLeg="c1"/>
S:<response id="A005"/>

S:<callUpdateRequest callLeg="c1" tag="device2">SDP:Y(offer)</callUpdateRequest>
Клиент удаляет проигрыватель "тонов дозвона", связанный с тегом "device2".
Клиент создаёт новый "маркированный" медиа-объект B и связывает его с тегом "device2". медиа-объект B настроен для работы в режиме "только принимать".
Клиент передаёт полученный SDP:Y(offer) в качестве "предложения" SDP медиа-объекту B.
Клиент получает "ответ" SDP от этого медиа-объекта: SDP:B(answer), и передаёт его серверу:
C:<callUpdateAccept id="A006" callLeg="c1">SDP:B(answer)</callUpdateAccept>
S:<response id="A006"/>

S:<callConnected callLeg="c1" tag="device1">SDP:X(answer3)</callConnected>
Клиент удаляет проигрыватели "тонов дозвона", удаляет "маркированный" медиа-объект B и передаёт полученный дескриптор SDP:X(answer3) (это - "ответ" SDP) своему "немаркированному" медиа-объекту A.

Сообщение <callConnected/> вообще могло прийти без SDP:
S:<callConnected callLeg="c1" tag="device1"/>
Клиент удаляет проигрыватели "тонов дозвона", удаляет "маркированный" медиа-объект B и использует дескриптор SDP:X(answer2), поскольку он был последним сохранённым для тега "device1". Клиент передаёт сохранённый дескриптор SDP:X(answer2) (это - "ответ" SDP) своему "немаркированному" медиа-объекту A.

Сообщение <callConnected/> вообще могло прийти без SDP и с другим тегом:
S:<callConnected callLeg="c1" tag="device2"/>
Клиент удаляет проигрыватели "тонов дозвона", удаляет "немаркированный" медиа-объект A и удаляет маркировку с медиа-объекта B (связанного с тегом "device2").


Звонок установлен, медиа-объект (A или B) настроен для работы в режиме "отправлять и получать", начался обмен медиаданными.
C:<callUpdateAccept id="A007" callLeg="c1"/>
S:<response id="A007"/>

Пользователь решает завершить звонок, Клиент завершает звонок и освобождает связанные с ним ресурсы Сервера:
S:<callKill id="A008" callLeg="c1" />
S:<response id="A008"/>
Звонок заканчивается, Клиент удаляет "немаркированный" медиа-объект A.

Пример Исходящий-04. Сессия исходящего звонка с начальным SDP, несколько устройств на принимающей стороне. медиа-объект не поддерживает "расщепление", дополнительные сообщения от вызываемых устройств.

Клиент создаёт медиа-объект A и использует его как "немаркированный" медиа-объект для нового звонка.
Клиент получает "предложение" SDP от этого объекта: SDP:A(offer)
C:<callStart id="A001" callLeg="c1" peer="user@domain">SDP:A(offer)</callStart>
S:<response id="A001"/>

S:<callProvisioned callLeg="c1" tag="device1"/>
Клиент создаёт проигрыватель "тонов дозвона", чтобы дать понять пользователю, что происходит вызов абонента.
C:<callUpdateAccept id="A002" callLeg="c1"/>
S:<response id="A002"/>

S:<callProvisioned callLeg="c1" tag="device2"/>
Клиент создаёт ещё один проигрыватель "тонов дозвона", чтобы пользователь знал о факте дозвона. Оба проигрывателя издают тоны дозвона (КПВ).
C:<callUpdateAccept id="A003" callLeg="c1"/>
S:<response id="A003"/>

S:<callProvisioned callLeg="c1" tag="device1">SDP:X(answer1)</callProvisioned>
Клиент сохраняет полученный SDP:X(answer1) и связывает его с тегом "device1". Изменений в медиа нет, оба проигрывателя издают тоны дозвона (КПВ).
C:<callUpdateAccept id="A004" callLeg="c1"/>
S:<response id="A004"/>

S:<callProvisioned callLeg="c1" tag="device1">SDP:X(answer2)</callProvisioned>
Клиент сохраняет полученный SDP:X(answer2) и связывает его с тегом "device1". Он заменяет полученный ранее с этим тегом SDP:X(answer1). Изменений в медиа нет, оба проигрывателя издают тоны дозвона (КПВ).
C:<callUpdateAccept id="A005" callLeg="c1"/>
S:<response id="A005"/>

S:<callUpdateRequest callLeg="c1" tag="device2">SDP:Y(offer)</callUpdateRequest>
Клиент удаляет проигрыватель "тонов дозвона", связанный с тегом "device2".
Клиент создаёт новый медиа-объект B и связывает его с тегом "device2". медиа-объект B настроен для работы в режиме "только принимать".
Клиент передаёт полученный SDP:Y(offer1) в качестве "предложения" SDP медиа-объекту B.
Клиент получает "ответ" SDP от этого медиа-объекта: SDP:B(answer), и передаёт его серверу:
C:<callUpdateAccept id="A006" callLeg="c1">SDP:B(answer)</callUpdateAccept>
S:<response id="A006"/>

S:<callUpdateRequest callLeg="c1" tag="device2">SDP:Y(offer2)</callUpdateRequest>
Клиент использует полученный SDP для передачи его существующему медиа-объекту B, связанному с тегом "device2".
Если это невозможно, Клиент создаёт новый медиа-объект C, передаёт ему полученный дескриптор SDP:Y(offer2) в качестве "предложения" SDP, и получает от него "ответ" SDP:C(answer). В случае успеха, Клиент удаляет медиа-объект B и "маркирует" вновь созданный медиа-объект C, связывая его с тегом "device2".
Новый медиа-объект C настроен для работы в режиме "только принимать".
Клиент передаёт полученный "ответ" SDP на Сервер:
C:<callUpdateAccept id="A007" callLeg="c1">SDP:C(answer)</callUpdateAccept>
S:<response id="A007"/>

S:<callUpdateSolicited callLeg="c1" tag="device3"/>
Клиент создаёт новый медиа-объект D и связывает его с тегом "device3".
Новый медиа-объект D настроен для работы в режиме "только принимать".
Клиент получает от этого медиа-объекта "предложение" SDP:D(offer) и посылает его на Сервер в теле запроса `callUpdate`.
C:<callUpdate id="A008" callLeg="c1">SDP:D(offer)</callUpdate>
S:<response id="A008"/>

Сервер отвечает сообщением `callUpdated`:
S:<callUpdated callLeg="c1" tag="device3">SDP:Z(answer)</callUpdated>
Клиент должен передать полученный дескриптор SDP медиа-объекту D как "ответ" SDP.

S:<callConnected callLeg="c1" tag="device1">SDP:X(answer3)</callConnected>
Клиент удаляет все проигрыватели "тонов дозвона", удаляет "маркированные" медиа-объекты (C и D) и передаёт полученный дескриптор SDP:X-3 (это - "ответ" SDP) "немаркированному" медиа-объекту A.

Сообщение <callConnected/> вообще могло прийти без SDP:
S:<callConnected callLeg="c1" tag="device1"/>
Клиент удаляет проигрыватели "тонов дозвона", удаляет все "маркированные" медиа-объекты (C и D) и использует дескриптор SDP:X(answer2), поскольку он был последним сохранённым для тега "device1". Клиент передаёт сохранённый дескриптор SDP:X(answer2) (это - "ответ" SDP) своему "немаркированному" медиа-объекту A.

Сообщение <callConnected/> вообще могло прийти без SDP и с другим тегом:
S:<callConnected callLeg="c1" tag="device2"/>
Клиент удаляет все проигрыватели "тонов дозвона", удаляет "немаркированный" медиа-объект A и "маркированный" медиа-объект D удаляет маркировку с медиа-объекта C (связанного с тегом "device2").

Сообщение <callConnected/> вообще могло прийти без SDP и с другим тегом:
S:<callConnected callLeg="c1" tag="device3"/>
Клиент удаляет все проигрыватели "тонов дозвона", удаляет "немаркированный" медиа-объект A и "маркированный" медиа-объект С и удаляет маркировку с медиа-объекта D (связанного с тегом "device3").

Звонок установлен, "немаркированный" медиа-объект (A, C или D) настроен для работы в режиме "отправлять и получать", начался обмен медиаданными.
C:<callUpdateAccept id="A007" callLeg="c1"/>
S:<response id="A007"/>

Пользователь решает завершить звонок, Клиент завершает звонок и освобождает связанные с ним ресурсы Сервера:
S:<callKill id="A008" callLeg="c1" />
S:<response id="A008"/>
Звонок заканчивается, Клиент удаляет "немаркированный" медиа-объект A.

Пример Исходящий-11. Сессия исходящего звонка без начального SDP.

Клиент не создаёт медиа-объект перед звонком.
C:<callStart id="A001" callLeg="c1" peer="user@domain"/>
S:<response id="A001"/>

S:<callProvisioned callLeg="c1" tag="device1"/>
Клиент создаёт проигрыватель "тонов дозвона", чтобы дать понять пользователю, что происходит вызов абонента.
C:<callUpdateAccept id="A002" callLeg="c1"/>
S:<response id="A002"/>

S:<callProvisioned callLeg="c1" tag="device1"/>
У Клиента уже есть проигрыватель "тонов дозвона" для этого устройства (тега), поэтому дополнительные операции с медиа не нужны.
C:<callUpdateAccept id="A003" callLeg="c1"/>
S:<response id="A003"/>

S:<callConnected callLeg="c1" tag="device1">SDP:X-1</callConnected>
Клиент удаляет проигрыватель "тонов дозвона", создаёт "немаркированный" медиа-объект A и передаёт полученный дескриптор SDP:X-1 (это - "ответ" SDP) "немаркированному" медиа-объекту A.
Клиент получает "ответ" SDP (SDP:A-1) от медиа-объекта A и посылает его на сервер:
C:<callUpdateAccept id="A004" callLeg="c1">SDP:A-1</callUpdateAccept>
S:<response id="A004"/>
Звонок установлен, медиа-объект A настроен для работы в режиме "отправлять и получать", начался обмен медиаданными.

S:<callDisconnected callLeg="inp01" />
Звонок завершается, Клиент удаляет "немаркированный" медиа-объект A.

Клиент освобождает ресурсы Сервера, занятые в звонке:
C:<callKill id="A005" callLeg="c1"/>
S:<response id="A005"/>

Пример Исходящий-12. Сессия исходящего звонка без начального SDP, несколько устройств на принимающей стороне.

Клиент не создаёт медиа-объект перед звонком.
C:<callStart id="A001" callLeg="c1" peer="user@domain"/>
S:<response id="A001"/>

S:<callProvisioned callLeg="c1" tag="device1"/>
Клиент создаёт проигрыватель "тонов дозвона", чтобы дать понять пользователю, что происходит вызов абонента.
C:<callUpdateAccept id="A002" callLeg="c1"/>
S:<response id="A002"/>

S:<callProvisioned callLeg="c1" tag="device2"/>
Клиент создаёт ещё один проигрыватель "тонов дозвона", чтобы пользователь знал о факте дозвона. Оба проигрывателя издают тоны дозвона (КПВ).
C:<callUpdateAccept id="A003" callLeg="c1"/>
S:<response id="A003"/>

S:<callProvisioned callLeg="c1" tag="device2">SDP:X-1</callProvisioned>
Клиент сохраняет полученный SDP:X(answer1) и связывает его с тегом "device2".
Клиент создаёт медиа-объект А, маркирует и связывает его с тегом "device2".
Клиент создаёт немаркированный медиа-объект A, и передаёт ему полученный SDP:X-1 ("предложение" SDP) .
Клиент получает "ответ" SDP от медиа-объекта A, и шлёт его на Сервер.
C:<callUpdateAccept id="A004" callLeg="c1">SDP:A-1</callUpdateAccept>
S:<response id="A004"/>

S:<callConnected callLeg="c1" tag="device1">SDP:Y-1</callConnected>
Клиент удаляет "проигрыватель дозвона" и медиа-объект A (маркированный тегом "device2").
Клиент создаёт немаркированный медиа-объект B, и передаёт ему полученный SDP:Y-1 ("предложение" SDP) .
Клиент получает "ответ" SDP от медиа-объекта B (SDP:B-1), и шлёт его на Сервер.
Звонок установлен, медиа-объект B настроен для работы в режиме "отправлять и получать", начался обмен медиаданными.
C:<callUpdateAccept id="A005" callLeg="c1">SDP:B-1</callUpdateAccept>
S:<response id="A005"/>

Сообщение <callConnected/> вообще могло прийти без SDP и с другим тегом:
S:<callConnected callLeg="c1" tag="device2"/>
Клиент удаляет проигрыватели "тонов дозвона", удаляет маркировку с медиа-объекта A (прежде - маркированного и связанного с тегом "device2").
Звонок установлен, медиа-объект A настроен для работы в режиме "отправлять и получать", начался обмен медиаданными.
C:<callUpdateAccept id="A005" callLeg="c1"/>
S:<response id="A005"/>

Пользователь решает завершить звонок, Клиент завершает звонок и освобождает связанные с ним ресурсы Сервера:
S:<callKill id="A006" callLeg="c1" />
S:<response id="A006"/>
Звонок заканчивается, Клиент удаляет "немаркированный" медиа-объект A.

Мгновенные Сообщения

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

sendIM

Эта операция отправляет Мгновенное Сообщение указанному пользователю. Сервер отправляет XIMSS ответ не ожидая фактической доставки Мгновенного сообщения.
Отдельной операции для открытия сессии Мгновенных Сообщений нет. Если Сервер не имеет открытой сессии Мгновенных Сообщений с указанным абонентом, то создаётся новая сессия.

Атрибуты:

• peer

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

• clientID

  необязательно; имя или идентификатор устройства абонента, на которое надо доставить Мгновенное Сообщение.

• type

  необязательно; тип сообщения согласно протоколу XMPP: chat, groupchat и т.д.

• iqid

  необязательно; строка идентификатора сообщения.

Тело:

• текст Мгновенного Сообщения (в кодировке UTF-8) или
• элемент XML body, содержащий текст Мгновенного Сообщения в теле, возможно, вместе с другими элементами XML сообщения. Или
• элемент XML composing (этот элемент надо посылать, когда пользователь приготовил сообщение, но пока его не отправил). Или
• элемент XML paused (этот элемент надо посылать, когда пользователь перестал набирать сообщение перед отправкой). Или
• элемент XML gone (этот элемент надо посылать, когда пользователь закончил разговор).
• элемент XML subject: его текстовое тело является строкой темы сообщения.

closeIM

Запрос на закрытие всех сессий Мгновенных Сообщений с указанным пользователем.
Клиентское приложения должно отправлять этот запрос при закрытии окна обмена Мгновенными Сообщениями.

Атрибуты:

• peer

  адрес электронной почты пользователя.

Сервер присылает следующие сообщения с данными:

readIM

Эти асинхронные сообщения данных присылаются, когда Сервер получает Мгновенное Сообщение для клиента пользователя.

Атрибуты:

• peer

  адрес электронной почты отправителя.

• peerName

  необязательно; настоящее имя отправителя.

• clientID

  необязательно; имя или идентификатор устройства абонента, с которого было отправлено Мгновенное Сообщение.

• subject

  необязательно; строка с темой сообщения (при использовании базового формата).

• iqid

  необязательно; строка идентификатора сообщения.

• gmtTime

  необязательно; отметка времени получения сообщения.

Тело:

• элемент XML composing; этот элемент присылается, когда абонент готовит (набирает) сообщение, но пока его не отправляет. Или

• элемент XML paused; этот элемент присылается, когда абонент приостановил набор сообщения. Или

• элемент XML gone; этот элемент присылается, когда пользователь закончил разговор. Или

• содержимое сообщения в базовом или расширенном формате, согласно последнему запросу signalBind:

  • простой формат:

    текст Мгновенного Сообщения (в кодировке UTF-8)

  • расширенный формат:

    элемент XML body, содержащий текст Мгновенного Сообщения в теле, возможно, вместе с другими элементами XML сообщения. элемент XML subject: его текстовое тело является строкой темы сообщения.

Операции явного открытия сессии не существует. Если у клиента отсутствуют открытое окно по обмену Мгновенными Сообщениями для указанного пользователя, то он должен открыть новое окно.

errorIM

Эти асинхронные сообщения данных присылаются, когда Сервер не смог доставить Мгновенное Сообщение.

Атрибуты:

• peer

  адрес электронной почты получателя.

• errorText

  текст сообщения об ошибке.

• signalCode

  числовой код ошибки.

• sendid

  атрибут id той операции sendIM, в которой произошла ошибка при отправке Мгновенного Сообщения.

Ростер и Статус Присутствия

Модель Ростера и Статуса Присутствия построена согласно модели протокола XMPP.

Ростером является набор элементов данных, каждый из которых описывает "контакт" - некоторого другого локального или удалённого пользователя. Пользователь может быть наблюдать за информацией о статусе присутствия "контакта", а "контакту" могут быть предоставлены права на наблюдение за информацией о статусе присутствия пользователя.

rosterList

Эта операция запрашивает все активные элементы данных Ростера.

Атрибуты:

• accountName

  если этот необязательный атрибут задан, то операция читает элементы Ростера указанного Пользователя.
  Сервер отправляет сообщения данных rosterItem для всех активных "контактов" Ростера.

rosterSet

Эта операция изменяет "контакт" в Ростере.

Атрибуты:

• accountName

  если этот необязательный атрибут задан, то операция изменяет Ростер указанного Пользователя.

• peer

  адрес электронной почты контакта.

• subscription

  необязательный атрибут:

  • update или без атрибутов: изменяет информацию о контакте.
  • remove: удаляет контакт из Ростера.
  • subscribed: подтверждает запрос контакта на наблюдение за информацией о статусе присутствия пользователя.
  • unsubscribed: отвергает запрос контакта на наблюдение за информацией о статусе присутствия пользователя или отзывает ранее предоставленное право на наблюдение.
  • subscribe: отправляет запрос на наблюдение за информацией о статусе присутствия контакта.
  • subBoth: подтверждает запрос контакта на наблюдение за информацией о статусе присутствия пользователя и отправляет запрос на наблюдение за информацией о статусе присутствия контакта.
  • unsubscribe: останавливает наблюдение за информацией о статусе присутствия контакта.

• name

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

Тело:

набор элементов XML group; тело каждого элемента указывает имя Группы, которой принадлежит этого контакт.

Операции update, subscribed и subscribe создают новую запись в Ростере, если ранее элемент данных с таким адресом не существовал.

rosterGroupSet

Эта операция управляет "группами контактов" в Ростере.

Атрибуты:

• accountName

  если этот необязательный атрибут задан, то операция изменяет Ростер указанного Пользователя.

• group

  имя группы.

• mode

  • add: создаёт новую группу контактов с указанным именем.
  • delete: удаляет существующую группу контактов с указанным именем из Ростера.
  • rename: переименовывает существующую группу контактов.

• newName

  новое имя группы контактов (используется только если атрибут mode имеет значение rename).

presenceSet

Эта операция устанавливает статус присутствия пользователя. Сервер собирает информацию о статусе присутствия от всех подключённых клиентов (XIMSS, XMPP, SIP) и распространяет её всем подписчикам.

Атрибуты:

• type

  этот необязательный элемент может иметь значение unavailable. Он указывает, что пользователь "как будто вне сети".
  Если этот атрибут отсутствует, то пользователь находится в сети.

Тело:

необязательный XML элемент show; его текстовое тело указывает статус присутствия пользователя согласно протоколу XMPP:

• dnd - Не беспокоить, Занят(а), На телефоне.
• away - Скоро вернусь, На совещании, На перерыве.
• xa - Нет на месте ("расширенное" Нет на месте).

В качестве альтернативы вы можете использовать элемент XML presence вместо элемента XML show. Тело текстового XML элемента presence содержит более подробный статус присутствия пользователя:

• offline - "как будто вне сети".
• online - В сети.
• on-phone - пользователь в настоящее время разговаривает по телефону.
• in-meeting - пользователь находится на совещании.
• busy - общая форма для "не могу сейчас говорить".
• be-back - пользователь скоро вернётся
• out-lunch - пользователь вышел на перерыв.
• away - Нет на месте.

Тело элемента XML может содержать элемент XML status: его текстовое тело задаёт произвольное сообщение о статусе. Для удаления заданного прежде произвольного сообщения о статусе надо передать пустой объект XML status.

В начале сессии пользователь находится "как будто вне сети". Клиент должен использовать эту операцию, чтобы показать, что пользователь находится в сети.

Когда пользователь отсоединяется, статус его сессии автоматически меняется на unavailable (вне сети).

Эта операция может использоваться для отправки информации о статусе занятости конкретному устройству (например, для подключения к групповому чату по протоколу XMPP). Чтобы отправить информацию о статусе занятости (а не только установить её), надо использовать дополнительные атрибуты:

• Атрибуты:

• peer

  адрес электронной почты пользователя или группового чата, которому необходимо отправить информацию о статусе занятости.

• clientID

  необязательно; имя или идентификатор устройства абонента, на которое надо доставить информацию о статусе занятости.

Сервер присылает следующие сообщения с данными:

rosterItem

Эти сообщения с данными отправляются синхронно при обработке Сервером запроса rosterList. Для каждого элемента данных Ростера (для каждого "Контакта") отправляется одно сообщение.
Эти сообщения данных также могут быть отправлены асинхронно (смотрите ниже).

• Атрибуты:

• peer

  адрес электронной почты контакта.

• subscription

  • to: пользователь может наблюдать за контактом.
  • from: контакт может наблюдать за пользователем.
  • both: пользователь и контакт могут наблюдать друг за другом.
  • none: пользователь и контакт не могут наблюдать друг за другом.

• ask

  этот необязательный атрибут имеет значение subscribe, если пользователь запросил подписку на информацию о статусе присутствия контакта, но этот запрос ещё не был подтверждён.

• name

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

• Тело:

набор элементов XML group; тело каждого элемента указывает имя Группы, которой принадлежит этого контакт.
Если для разрешения уведомлений Ростера и Статуса Присутствия была использована операция signalBind:

• Каждый раз, когда элемент данных Ростера добавляется или изменяется, Сервер отправляет сообщения rosterItem с новыми или изменёнными данными.
• Каждый раз, когда элемент данных Ростера удаляется, Сервер отправляет сообщения rosterItem с атрибутом subscription, имеющим значение remove.
• Сервер отправляет сообщения с данными presence.

presence

Эти асинхронные сообщения с данными отправляются, когда статус присутствия некоторого "контакта" (элемента Ростера) изменяется и уведомления об изменении Статуса включены.

Атрибуты:

• peer

  адрес электронной почты контакта.

• type

  необязательный атрибут:

  • unavailable: контакт находится вне сети.
  • subscribe: контакт требует подписку на информацию о статусе присутствия пользователя.
  • отсутствует: контакт в сети.

Тело:

элемент XML presence; его текстовое тело указывает детализированный статус присутствия контакта (смотрите выше);
необязательный элемент XML show; его текстовое тело указывает статус присутствия контакта в стиле XMPP (смотрите выше).

Эти асинхронные сообщения с данными присылаются также, когда удалённый абонент присылает свою информацию о занятости именно в эту сессию протокола XIMSS (например, групповой чат информирует эту сессию о пользователях - присоединяющихся и покидающих чат). В этом случае сообщение с данными содержит дополнительные атрибуты.

Атрибуты:

• clientID

  имя или идентификатор устройства абонента, с которого было отправлено сообщение о статусе присутствия.

Полнотекстовый Поиск

emailSearch

Эта операция производит поиск искомой строки с поддержкой Синтаксиса Запросов в Индексе Поиска и, в результате, присылает сообщение searchResult с найденными данными. При некорректном формате строки операция не будет обработана, а сервер вернёт ошибку Invalid Query.

Набор элементов XML:

• searchString

  искомая строка.

• searchOptions

  параметры поиска писем

Пример:

C:<emailSearch>
C:    <subKey key="searchString">Богатырь</subKey>
C:</emailSearch>
S:<searchResult>
S:    <subKey key="count">
S:        <number>1</number>
S:    </subKey>
S:    <subKey key="limit">
S:        <number>50</number>
S:    </subKey>
S:    <subKey key="mails">
S:        <subValue>
S:            <subKey key="Attachments"/>
S:            <subKey key="Bcc"/>
S:            <subKey key="Body"/>
S:            <subKey key="Cc"/>
S:            <subKey key="Date">20240823T151404Z</subKey>
S:            <subKey key="Flags">
S:                <subValue>Seen</subValue>
S:            </subKey>
S:            <subKey key="From">bob@domain.local</subKey>
S:            <subKey key="In-Reply-To"/>
S:            <subKey key="Message-ID">&lt;ximss-7740009@domain.local&gt;</subKey>
S:            <subKey key="References"/>
S:            <subKey key="Subject">Бородино</subKey>
S:            <subKey key="To">alice</subKey>
S:            <subKey key="X-Priority"/>
S:            <subKey key="boxSeq">
S:                <number>1722948</number>
S:            </subKey>
S:            <subKey key="mailboxName">Sent Items</subKey>
S:            <subKey key="messageUid">
S:                <number>2</number>
S:            </subKey>
S:            <subKey key="size">
S:                <number>5151</number>
S:            </subKey>
S:        </subValue>
S:    </subKey>
S:    <subKey key="offset">
S:        <number>0</number>
S:    </subKey>
S:    <subKey key="total">
S:        <number>2</number>
S:    </subKey>
S:</searchResult>

calendarSearch

Эта операция производит поиск искомой строки с поддержкой Синтаксиса Запросов в Индексе Поиска и, в результате, присылает сообщение searchResult с найденными данными. При некорректном формате строки операция не будет обработана, а сервер вернёт ошибку Invalid Query.

Набор элементов XML:

• searchString

  искомая строка.

• searchOptions

  Параметры поиска календарных событий

Пример

C:<calendarSearch>
C:    <subKey key="searchString">Богатырь</subKey>
C:    <subKey key="searchOptions">
C:        <subkey key="limit">
C:            <number>10</number>
C:        </subkey>
C:        <subKey key="offset">
C:            <number>0</number>
C:        </subKey>
C:    </subKey>
C:</calendarSearch>
S:<searchResult>
S:    <subKey key="calendarEvents">
S:        <subValue>
S:            <subKey key="Attachments"/>
S:            <subKey key="Date">20250615T201258Z</subKey>
S:            <subKey key="Message-ID">&lt;PUBLISH-0-875009182.1.bob&gt;</subKey>
S:            <subKey key="Subject">Богатырская тема</subKey>
S:            <subKey key="attendees">Alice &lt;alice@domain.local&gt; ted@domain.local Переговорка &lt;resource@domain.local&gt;</subKey>
S:            <subKey key="boxSeq">
S:                <number>1722953</number>
S:            </subKey>
S:            <subKey key="description">
S:                <binString>
S:                    <base64>PGI+0JHQvtCz0LDRgtGL0YDRjDwvYj4K0J7Qv9C40YHQsNC90LjQtQ==</base64>
S:                </binString>
S:            </subKey>
S:            <subKey key="end">20250617T083000Z</subKey>
S:            <subKey key="isAllDay">no</subKey>
S:            <subKey key="location">Переговорка, Москва, Башня Федерация</subKey>
S:            <subKey key="mailboxName">Calendar</subKey>
S:            <subKey key="messageUid">
S:                <number>164</number>
S:            </subKey>
S:            <subKey key="organizer">Bob &lt;bob@domain.local&gt;</subKey>
S:            <subKey key="size">
S:                <number>1520</number>
S:            </subKey>
S:            <subKey key="start">20250617T080000Z</subKey>
S:            <subKey key="summary">Богатырская тема</subKey>
S:        </subValue>
S:    </subKey>
S:    <subKey key="count">
S:        <number>1</number>
S:    </subKey>
S:    <subKey key="limit">
S:        <number>10</number>
S:    </subKey>
S:    <subKey key="offset">
S:        <number>0</number>
S:    </subKey>
S:    <subKey key="total">
S:        <number>1</number>
S:    </subKey>
S:</searchResult>

searchInIndex

Обратите внимание

Начиная с версии сервера 6.5.2, для поиска писем рекомендуется использовать функцию emailSearch.

Эта операция производит поиск искомой строки с поддержкой Синтаксиса Запросов в Индексе Поиска и, в результате, присылает сообщение searchResult с найденными данными. При некорректном формате строки операция не будет обработана, а сервер вернёт ошибку Invalid Query.

Набор элементов XML:

• searchString

  искомая строка.

• searchOptions

  параметры общего поиска.

Пример:

C:<searchInIndex id="A001">
C:  <subKey key="searchString">привет</subKey>
C:  <subKey key="searchOptions">
C:    <subkey key="limit"><number>10</number></subkey>
C:    <subKey key="offset"><number>0</number></subKey>
C:  </subKey>
C:</searchInIndex>
S:<searchResult>
S:  <subKey key="limit">
S:    <number>10</number>
S:  </subKey>
S:  <subKey key="offset">
S:    <number>0</number>
S:  </subKey>
S:  <subKey key="total">
S:    <number>1</number>
S:  </subKey>
S:  <subKey key="count">
S:    <number>1</number>
S:  </subKey>
S:  <subKey key="mails">
S:    <subValue>
S:      <subKey key="Subject">[Comm] test</subKey>
S:      <subKey key="Body">
S:        <binString>
S:          <base64>0J/RgNC40LLQtdGCLCDQnNC40YAh</base64>
S:        </binString>
S:      </subKey>
S:      <subKey key="Date">20250304T144659</subKey>
S:      <subKey key="From">&quot;Bob&quot; &lt;bob@example.com&gt;</subKey>
S:      <subKey key="To">&quot;Alice&quot; &lt;alice@example.com&gt;</To>
S:      <subKey key="Cc"/>
S:      <subKey key="Bcc"/>
S:      <subKey key="In-Reply-To"/>
S:      <subKey key="Message-ID">&lt;gj2v6a$prm$1@example.com&gt;</subKey>
S:      <subKey key="References"/>
S:      <subKey key="mailboxName">INBOX</subKey>
S:      <subKey key="boxSeq">
S:        <number>1</number>
S:      </subKey>
S:      <subKey key="calendarEvent">
S:        <subKey key="attendees"/>
S:        <subKey key="description"/>
S:        <subKey key="end"/>
S:        <subKey key="isAllDay">no</subKey>
S:        <subKey key="location"/>
S:        <subKey key="organizer"/>
S:        <subKey key="start"/>
S:      </subKey>
S:      <subKey key="messageUid">
S:        <number>1</number>
S:      </subKey>
S:      <subKey key="size">
S:        <number>695</number>
S:      </subKey>
S:      <subKey key="type">mail</subKey>
S:    </subValue>
S:  </subKey>
S:</searchResult>
S:<response id="A001"/>

Параметры поиска писем

Параметры поиска определяют, какие результаты будут получены из Индекса Поиска при поиске писем.

• limit

  максимальное количество сообщений, которое нужно вернуть. По умолчанию - 50.

• offset

  количество сообщений, которые нужно пропустить перед выборкой. По умолчанию - 0.

• fragmentSize

  размер фрагмента с текстом, в котором найдена искомая строка. Длина фрагмента достигает указанного значения, но обрезка происходит по границе слова. По умолчанию текст возвращается в полном объёме.

• preTag

  открывающий тег для выделения искомой строки. По умолчанию <b>.

• postTag

  закрывающий тег для выделения искомой строки. По умолчанию </b>.

• returnBody

  если значение установлено в yes, текст письма будет включён в результаты запроса. По умолчанию — не включается.

• dateFrom

  начальная дата сообщений в выборке в формате Unix Timestamp. По умолчанию - 0, что соответствует 1970-01-01T00:00:00Z.

• dateTo

  конечная дата сообщений в выборке в формате Unix Timestamp. По умолчанию - 4294967295, что соответствует 2106-02-07T06:28:15Z.

• fields

  массив полей, по которым происходит поиск искомой строки. По умолчанию - ["From", "To", "Cc", "Bcc", "Subject", "Body", "Attachments"].

• mailboxNames

  массив имён почтовых ящиков, по которым происходит поиск искомой строки. По умолчанию - все ящики.

• subject

  тема письма. Параметр поддерживает Синтаксис Запросов. По умолчанию параметр игнорируется.

• from

  почтовый адрес или имя отправителя. Параметр поддерживает Синтаксис Запросов. По умолчанию параметр игнорируется.

• to

  почтовый адрес или имя получателя. Параметр поддерживает Синтаксис Запросов. По умолчанию параметр игнорируется.

• cc

  почтовый адрес или имя получателя в копии. Параметр поддерживает Синтаксис Запросов. По умолчанию параметр игнорируется.

• bcc

  почтовый адрес или имя получателя в скрытой копии. Параметр поддерживает Синтаксис Запросов. По умолчанию параметр игнорируется.

• requiredFlags

  массив флагов, письма с которыми включаются в выборку. По умолчанию параметр игнорируется.

• excludedFlags

  массив флагов, письма с которыми исключаются из выборки. По умолчанию параметр игнорируется.

• priority

  приоритет письма (1–5) из заголовка X-Priority, где 1 – наивысший, 5 – самый низкий. По умолчанию параметр игнорируется.

• attachmentTypes

  массив типов вложений, сообщения с которыми включаются в выборку, например ["PDF", "DOCX"]. Типы вложений регистронезависимы. Если важно только наличие вложений, независимо от их типа, укажите звёздочку (*), например ["*"]. По умолчанию параметр игнорируется.

• sortField

  поле, по которому будут отсортированы результаты поиска. По умолчанию используется сортировка по дате.

• sortOrder

  порядок сортировки. Возможные значения: asc (прямой порядок) и desc (обратный порядок). По умолчанию используется обратный порядок (desc).

Параметры поиска календарных событий

Параметры поиска определяют, какие результаты будут получены из Индекса Поиска при поиске календарных событий.

• limit

  максимальное количество сообщений, которое нужно вернуть. По умолчанию - 50.

• offset

  количество сообщений, которые нужно пропустить перед выборкой. По умолчанию - 0.

• fragmentSize

  размер фрагмента с текстом, в котором найдена искомая строка. Длина фрагмента достигает указанного значения, но обрезка происходит по границе слова. По умолчанию текст возвращается в полном объёме.

• preTag

  открывающий тег для выделения искомой строки. По умолчанию <b>.

• postTag

  закрывающий тег для выделения искомой строки. По умолчанию </b>.

• returnBody

  если значение установлено в yes, тело календарного события будет включёно в результаты запроса. По умолчанию — не включается. Без указания не возвращается значение полей календарного события (summary, description, location, organizer, attendees, start, end, isAllDay, Attachments...).

• mailboxNames

  массив имён почтовых ящиков, по которым происходит поиск искомой строки. По умолчанию - все ящики.

• subject (summary)

  тема письма. Параметр поддерживает Синтаксис Запросов. По умолчанию параметр игнорируется.

• attachmentTypes

  массив типов вложений, сообщения с которыми включаются в выборку, например ["PDF", "DOCX"]. Типы вложений регистронезависимы. Если важно только наличие вложений, независимо от их типа, укажите звёздочку (*), например ["*"]. По умолчанию параметр игнорируется.

• calendarEventOrganizer

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

• calendarEventAttendees

  участники календарных событий. Параметр поддерживает Синтаксис Запросов. По умолчанию параметр игнорируется.

• calendarEventDateFrom

  начальная дата календарных событий в выборке в формате Unix Timestamp. По умолчанию - 0, что соответствует 1970-01-01T00:00:00Z.

• calendarEventDateTo

  конечная дата календарных событий в выборке в формате Unix Timestamp. По умолчанию - 4294967295, что соответствует 2106-02-07T06:28:15Z.

• sortField

  поле, по которому будут отсортированы результаты поиска. По умолчанию используется сортировка по дате.

• sortOrder

  порядок сортировки. Возможные значения: asc (прямой порядок) и desc (обратный порядок). По умолчанию используется обратный порядок (desc).

Параметры общего поиска

Параметры поиска определяют, какие результаты будут получены из Индекса Поиска.

• types

  массив типов сообщений в выборке. Принимает значения mail для писем, calendarEvent для календарных событий. По умолчанию — mail.

• limit

  максимальное количество сообщений, которое нужно вернуть. По умолчанию - 50.

• offset

  количество сообщений, которые нужно пропустить перед выборкой. По умолчанию - 0.

• fragmentSize

  размер фрагмента с текстом, в котором найдена искомая строка. Длина фрагмента достигает указанного значения, но обрезка происходит по границе слова. По умолчанию текст возвращается в полном объёме.

• preTag

  открывающий тег для выделения искомой строки. По умолчанию <b>.

• postTag

  закрывающий тег для выделения искомой строки. По умолчанию </b>.

• returnBody

  если значение установлено в yes, текст письма будет включён в результаты запроса. По умолчанию — не включается.

• dateFrom

  начальная дата сообщений в выборке в формате Unix Timestamp. По умолчанию - 0, что соответствует 1970-01-01T00:00:00Z.

• dateTo

  конечная дата сообщений в выборке в формате Unix Timestamp. По умолчанию - 4294967295, что соответствует 2106-02-07T06:28:15Z.

• fields

  массив полей, по которым происходит поиск искомой строки. По умолчанию - ["From", "To", "Cc", "Bcc", "Subject", "Body", "Attachments"].

• mailboxNames

  массив имён почтовых ящиков, по которым происходит поиск искомой строки. По умолчанию - все ящики.

• subject

  тема письма. Параметр поддерживает Синтаксис Запросов. По умолчанию параметр игнорируется.

• from

  почтовый адрес или имя отправителя. Параметр поддерживает Синтаксис Запросов. По умолчанию параметр игнорируется.

• to

  почтовый адрес или имя получателя. Параметр поддерживает Синтаксис Запросов. По умолчанию параметр игнорируется.

• cc

  почтовый адрес или имя получателя в копии. Параметр поддерживает Синтаксис Запросов. По умолчанию параметр игнорируется.

• bcc

  почтовый адрес или имя получателя в скрытой копии. Параметр поддерживает Синтаксис Запросов. По умолчанию параметр игнорируется.

• requiredFlags

  массив флагов, письма с которыми включаются в выборку. По умолчанию параметр игнорируется.

• excludedFlags

  массив флагов, письма с которыми исключаются из выборки. По умолчанию параметр игнорируется.

• priority

  приоритет письма (1–5) из заголовка X-Priority, где 1 – наивысший, 5 – самый низкий. По умолчанию параметр игнорируется.

• attachmentTypes

  массив типов вложений, сообщения с которыми включаются в выборку, например ["PDF", "DOCX"]. Типы вложений регистронезависимы. Если важно только наличие вложений, независимо от их типа, укажите звёздочку (*), например ["*"]. По умолчанию параметр игнорируется.

• calendarEventOrganizer

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

• calendarEventAttendees

  участники календарных событий. Параметр поддерживает Синтаксис Запросов. По умолчанию параметр игнорируется.

• calendarEventDateFrom

  начальная дата календарных событий в выборке в формате Unix Timestamp. По умолчанию - 0, что соответствует 1970-01-01T00:00:00Z.

• calendarEventDateTo

  конечная дата календарных событий в выборке в формате Unix Timestamp. По умолчанию - 4294967295, что соответствует 2106-02-07T06:28:15Z.

• sortField

  поле, по которому будут отсортированы результаты поиска. По умолчанию используется сортировка по дате.

• sortOrder

  порядок сортировки. Возможные значения: asc (прямой порядок) и desc (обратный порядок). По умолчанию используется обратный порядок (desc).

searchResult

Это сообщение отправляется, когда Сервер обрабатывает запрос searchInIndex, emailSearch, calendarSearch.

Тело:

Набор элементов XML:

• limit

  максимальное количество сообщений, которое нужно вернуть.

• offset

  количество сообщений, которые нужно пропустить перед выборкой.

• total

  общее количество найденных сообщений.

• count

  количество сообщений, которое вернулось в выборке.

• mails

  массив найденных сообщений, в ответ на запрос searchInIndex, emailSearch с полями:

  • Subject

  • Body

  • Date

  • From

  • To

  • Cc

  • Bcc

  • In-Reply-To

  • Message-ID

  • References

  • mailboxName

  • boxSeq

  • messageUid

  • size

  • type

    Возвращается только для запроса searchInIndex, позволяет определить, к какому типу относится элемент массива (почта или календарное событие).

• calendarEvents

  массив найденных календарных событий, в ответ на запрос calendarSearch с полями:

  • size
  • Attachments
  • Date
  • Message-ID
  • Subject
  • boxSeq
  • mailboxName
  • messageUid
  • summary
  • description
  • location
  • organizer
  • attendees
  • start
  • end
  • isAllDay

readSearchIndexState

В результате этой операции сервер присылает сообщение searchIndexState с текущим состоянием Индекса Поиска.

searchIndexState

Это сообщение отправляется, когда сервер обрабатывает запрос readSearchIndexState.

Тело:

строка с текущим состоянием Индекса Поиска, которая может иметь значения:

• none - Индекс отсутствует.
• waiting - Ожидает построения индекса.
• indexing - Индекс в процессе построения.
• ready - Индекс готов работе.

Цепочки писем (треды)

Цепочки писем (треды) формируются на основе заголовков Message-ID и In-Reply-To в соответствии с RFC5322:

• Message-ID — заголовок, содержащий уникальный идентификатор каждого письма.

• In-Reply-To — заголовок, содержащий Message-ID письма, на которое отправляется ответ.

Если письмо содержит заголовок In-Reply-To, оно считается ответом и добавляется в соответствующую цепочку. Если же In-Reply-To отсутствует, письмо считается началом новой цепочки.

fetchThread

Эта операция выполняет поиск всех писем, входящих в одну цепочку с указанным письмом, и в ответ отправляет сообщение thread, содержащее найденные письма.

Атрибуты:

• folder — Имя представления папки.

• UID — UID сообщения.

Пример:

C:<fetchThread id="A001" folder="INBOX" UID="1" />
S:<thread>
S:  <subKey key="mails">
S:    <subValue>
S:      <subKey key="Subject">Hello</subKey>
S:      <subKey key="Body">
S:        <binString>
S:          <base64>SGkgQWxpY2Uh</base64>
S:        </binString>
S:      </subKey>
S:      <subKey key="Date">20250304T144659</subKey>
S:      <subKey key="From">&quot;Bob&quot; &lt;bob@example.com&gt;</subKey>
S:      <subKey key="To">&quot;Alice&quot; &lt;alice@example.com&gt;</subKey>
S:      <subKey key="Cc"/>
S:      <subKey key="Bcc"/>
S:      <subKey key="In-Reply-To"/>
S:      <subKey key="Message-ID">&lt;gj2v6a$prm$1@example.com&gt;</subKey>
S:      <subKey key="References"/>
S:      <subKey key="mailboxName">INBOX</subKey>
S:      <subKey key="boxSeq">
S:        <number>1</number>
S:      </subKey>
S:      <subKey key="messageUid">
S:        <number>1</number>
S:      </subKey>
S:    </subValue>
S:    <subValue>
S:      <subKey key="Subject">RE: Hello</subKey>
S:      <subKey key="Body">
S:        <binString>
S:          <base64>SGkgQm9iIQ==</base64>
S:        </binString>
S:      </subKey>
S:      <subKey key="Date">20250304T144725</subKey>
S:      <subKey key="From">&quot;Alice&quot; &lt;alice@example.com&gt;</subKey>
S:      <subKey key="To">&quot;Bob&quot; &lt;bob@example.com&gt;</subKey>
S:      <subKey key="Cc"/>
S:      <subKey key="Bcc"/>
S:      <subKey key="In-Reply-To">&lt;gj2v6a$prm$1@example.com&gt;</subKey>
S:      <subKey key="Message-ID">&lt;bs4j8r$zht51@example.com&gt;</subKey>
S:      <subKey key="References">&lt;gj2v6a$prm$1@example.com&gt;</subKey>
S:      <subKey key="mailboxName">Sent Items</subKey>
S:      <subKey key="boxSeq">
S:        <number>2</number>
S:      </subKey>
S:      <subKey key="messageUid">
S:        <number>1</number>
S:      </subKey>
S:    </subValue>
S:  </subKey>
S:</thread>
S:<response id="A001" />

thread

Это сообщение с данными отправляется, когда сервер обрабатывает запрос fetchThread.

Тело:

Набор элементов XML:

• mails

  массив найденных сообщений, отсортированных по дате.

Запросы в стиле протокола XMPP

Клиент может отправлять и получать запросы, аналогичные запросам "iq" в протоколе XMPP.

iqSend

Эта операция отправляет запрос "iq" указанному пользователю. Сервер отправляет XIMSS ответ, не ожидая фактической доставки Мгновенного сообщения.

Атрибуты:

• peer

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

• clientID

  необязательно: имя или идентификатор устройства абонента, на которое надо доставить информацию о статусе занятости.

• type

  тип запроса "iq" XMPP (get, set, result или error).

• iqid

  значение этого атрибута задаёт значение атрибута id запроса "iq" XMPP.

Тело:

тело запроса "iq" XMPP.

Сервер присылает следующие сообщения с данными:

iqRead

Эти асинхронные сообщения данных присылаются, когда Сервер получает запрос "iq" XMPP для клиента пользователя.

Атрибуты:

• peer

  адрес электронной почты отправителя.

• clientID

  необязательно; имя или идентификатор устройства абонента, с которого было отправлено Мгновенное Сообщение.

• type

  тип запроса "iq" XMPP (get, set, result или error).

• iqid

  атрибут id принятого запроса "iq" XMPP.

Тело:

тело запроса "iq" XMPP.

Настройки

Клиент может получать и изменять Настройки аутентифицированного пользователя и данные О Себе ("Публично Доступные").

prefsRead

Эта операция получает Настройки аутентифицированного пользователя или его данные "О Себе" ("Публично Доступные").

Атрибуты:

• type

  это - необязательный параметр.
  Если указано значение default, то возвращаются Настройки, задаваемые для Пользователя Домена по умолчанию.
  Если указано значение custom, то возвращаются явно заданные Настройки Пользователя.
  Если указано значение publicInfo, то запрашиваются настройки Пользователя "О Себе" ("Публично Доступные").
  Если атрибут не указан, то будут получены все фактически действующие Настройки Пользователя.

Тело: Ноль или более элементов XML name. Тело этих элементов задаёт имена получаемых элементов; если не указано ни одного элемента name, то получаются все элементы Настроек или элементы "О Себе" ("Публично Доступные").

Сервер возвращает одно сообщение prefs.

prefsStore

Эта операция изменяет Настройки аутентифицированного пользователя или его данные "О Себе" ("Публично Доступные").

Атрибуты:

• type

  это - необязательный параметр.
  Если его значением является publicInfo, то изменяются Настройки Пользователя "О Себе" ("Публично Доступные").
  Если атрибут не указан, то будут обновлены все указанные Настройки Пользователя.

Тело:

Элементы XML с именами, совпадающими с именами элементов Настроек. Тело элемента содержит новое значение элемента Настроек. Если значением является строка default, то значения пользовательских Настроек или настроек "О Себе" ("Публично Доступные") удаляются и фактически действующими Настройками Пользователя становятся Настройки по умолчанию. Если значение является массивом, то он должен быть представлен с использованием представления XML для array. Если значением является словарь, то он должен быть представлен с использованием представления XML для dictionary.

Если тело содержит элемент UserFromAddr, то Сервер использует этот элемент и необязательный элемент UserFromName для составления элемента UserFrom, имеющим значение адрес электронной почты (в формате "UserFromName_value" <UserFromAddr_value>).

prefsReload

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

• Атрибуты:

  отсутствуют

Сервер присылает следующие сообщения с данными:

prefs

Это синхронное сообщение данных отправляется, когда Сервер обрабатывает запрос prefsRead.

Атрибуты:

• type

  необязательный атрибут, такой же как и атрибут запроса.

Тело:

Элементы XML с именами, совпадающими с именами элементов Настроек и элементов "О Себе". В теле элемента содержится значение элемента.
Если значение является массивом, то он представляется с использованием представления XML для array.
Если значением является словарь, то представляется с использованием представления XML для dictionary.

Если данные prefs содержат строку UserFrom, то Сервер пытается разобрать этот адрес электронной почты. Если адрес может быть разобран, то к телу сообщения данных добавляется элемент UserFromAddr (содержащим "чистый" адрес userName@domainName) и необязательный элемент UserFromName (с комментарием адреса).

prefsModified

Эти асинхронные сообщения данных отправляются при изменении Настроек Пользователя (в этой сессии, в другой сессии или некоторым другим компонентом Сервера CommuniGate Pro).
Рекомендуется, чтобы в ответ на это сообщение клиент прочитал Настройки Пользователя заново.

Операции с Хранилищем Файлов

Клиент может работать с Хранилищем Файлов Пользователя.
Если аутентифицированный пользователь имеет право администратора домена CanAccessWebSites (Полный доступ ко всем Файлам), то этот клиент, используя префикс перед именем файла ~accountName/fileName, может также работать с файлами, принадлежащими другому Пользователю.

fileList

Операция возвращает список файлов (с информацией о них) в директории Файлового Хранилища.

Атрибуты:

• directory

  необязательный атрибут с именем поддиректории в Хранилище Файлов. Если он и атрибут fileName отсутствуют, то возвращается содержимое корневой директории Пользователя в Хранилище Файлов.

• fileName

  необязательный атрибут, используемый только при отсутствии атрибута directory. Если он указан, то операция возвращает информацию только о файле или директории с именем из этого атрибута.

• gmtTime

  необязательный атрибут. Если он указан, то временные отметки в результате используют время GMT. Сервер возвращает одно сообщение fileInfo для каждого файла или директории, находящихся в указанной директории в Хранилище Файлов.

fileDirInfo

Эта операция возвращает информацию о всех файлах Пользователя или обо всех файлах, находящихся в указанной директории.

Атрибуты:

• directory

  необязательный атрибут с именем поддиректории в Хранилище Файлов. Если он отсутствует, то возвращается информация обо всех файлах в Хранилище Файлов Пользователя. Сервер возвращает одно сообщение fileDirInfo.

fileDirList

С помощью этой операции можно получить список всех папок в Хранилище Файлов. Сервер возвращает одно сообщение fileDirName для каждой директории Хранилища Файлов.

fileWrite

Эта операция сохраняет данные в файл.

Атрибуты:

• fileName

  имя записываемого файла.

• position

  Если этот атрибут отсутствует, то эта операция полностью перезаписывает указанный файл. Если файл не существовал, то он создаётся.
  Если значением этого атрибута является append, то эта операция добавляет данные в конец файла (атомарно).
  Если значением этого атрибута является new, то эта операция сначала проверяет что указанный файл не существует, а затем создаёт файл и сохраняет в нём данные.
  Если значением этого атрибута является число, то файл должен существовать, а операция перезаписывает файл, начиная с позиции (байта), указываемого этим числом.

• type

  Если этот необязательный атрибут задан со значением binary, то телом запроса должен быть элемент XML base64; перед записью в файл тело раскодируется из base64.
  Если этот необязательный атрибут задан со значением object, то телом запроса должно быть представление XML данных, содержащихся в Объекте; в файл записывается текстовое представление этого Объекта. Если это значение используется, то атрибут position не должен указываться.
  Если этот необязательный атрибут задан со значением xml, то тело запроса должно быть одним элементом XML. Его текстовое представление записывается в файл. Если это значение используется, то атрибут position не должен указываться.
  Если этот необязательный атрибут задан со значением vcard, то тело запроса должно быть одним элементом XML, представляющим объект vCard. Его текстовое представление (в формате vCard) записывается в файл. Если это значение используется, то атрибут position не должен указываться.

Тело:

Или текст с данными файла, или элемент XML base64, или объект в представлении XML, или элемент XML для записи в файл.

fileStore

Эта операция сохраняет загруженный на сервер файл или MIME часть сообщения как файл в Хранилище Файлов.

Атрибуты:

• fileName

  имя создаваемого файла.

• uploadID

  строка, идентифицирующая файл в "наборе загруженных файлов".

• folder, UID, partID

  эти атрибуты имеют тот же смысл, что и атрибуты операции fileRead. Они идентифицируют MIME часть сообщения, которую необходимо получить, раскодировать и сохранить как файл.

• calendar

  используйте этот атрибут вместо атрибута folder для копирования MIME части из открытого Календаря, а не из папки с сообщениями электронной почты.

• position

  этот необязательный атрибут имеет тот же смысл, что и в операции fileWrite.
  Должен быть задан или атрибут uploadID, или атрибут folder, или атрибут calendar. Эти атрибуты не могут быть заданы одновременно в одной операции fileStore.

fileRead

Эта операция читает данные из файла.

Атрибуты:

• fileName

  имя файла, который необходимо прочитать.

• position

  Этот числовой атрибут задаёт позицию в файле, с которой начинается чтение. Если этот атрибут отсутствует, то файл читается с начала (с позиции 0).

• limit

  Этот числовой атрибут задаёт максимальный размер читаемой порции данных. Если он указан, то он не должен превышать 3 Мб. Если он не указан, то используется ограничение в 3 Мб.

• type

  Если этот необязательный атрибут задан со значением binary, то данные файла возвращается в кодировке base64 как тело элемента XML base64.
  Если этот необязательный атрибут задан со значением object, то данные файла разбираются как текстовое представление Object и возвращается Объект в представлении XML. Если используется это значение, то атрибуты position и limit не должны указываться и размер файла не должен превышать 3 Мб.
  Если этот необязательный атрибут задан со значением xml, то данные файла разбираются как документ XML и возвращается содержимое XML. Если используется это значение, то атрибуты position и limit не должны указываться и размер файла не должен превышать 3 Мб.
  Если этот необязательный атрибут задан со значением vCard, то данные файла разбираются как документ vCard и возвращается представление XML для vCard. Если используется это значение, то атрибуты position и limit не должны указываться и размер файла не должен превышать 3 Мб. Сервер возвращает сообщение с данными fileData.

fileRename

Эта операция переименовывает файл в Хранилище Файлов.

Атрибуты:

• fileName

  имя файла, который необходимо переименовать.

• newName

  новое имя файла.

fileRemove

Эта операция удаляет файл из Хранилища Файлов.

Атрибуты:

• fileName

  имя файла, который необходимо удалить.

fileCopy

Эта операция копирует файл или содержимое сообщения в файл в Хранилище Файлов.

Атрибуты:

• newName

  имя создаваемого файла (для копии файла). Если файл с этим именем уже существует, то он удаляется.

• fileName

  необязательно: этот параметр задаёт имя файла, которое необходимо скопировать.

Тело:

необязательный элемент copyMIME. Он задаёт часть сообщения, которую снеобходимо декодировать и скопировать в указанный файл. Операция должна использовать либо атрибут fileName, либо один элемент тела copyMIME.

fileDirCreate

Эта операция создаёт файловую директорию в Хранилище Файлов.

Атрибуты:

• fileName

  имя файловой директории, которая будет создана.

fileDirRename

Эта операция переименовывает директорию в Хранилище Файлов.

Атрибуты:

• fileName

  имя переименовываемой директории.

• newName

  новое имя директории.

fileDirRemove

Эта операция удаляет директорию из Хранилища Файлов.

Атрибуты:

• fileName

  имя удаляемой директории. Удалены могут быть только пустые директории.

fileAttrRead

Эта операция считывает расширенные атрибуты файла или директории.

Атрибуты:

• fileName

  имя файла или директории.

Тело:

набор элементов XML field. Каждый элемент должен иметь текстовое тело, содержащее имя получаемого атрибута. Если ни один элемент field не указан, то возвращаются все атрибуты.
Сервер возвращает сообщение с данными fileAttrData.

fileAttrWrite

Эта операция изменяет расширенные атрибуты файла или директории.

Атрибуты:

• fileName

  имя файла или директории.

Тело:

набор элементов XML с атрибутами.
Если тело элемента XML содержит атрибут mode со значением delete, тогда все файловые атрибуты с именем в теле этого элемента XML будут удалены, а тело элемента XML не будет добавлено в качестве файлового атрибута.
Если тело элемента XML содержит атрибут mode со значением add, тогда тело этого элемента XML будет добавлено в атрибуты файла.
Если тело элемента XML содержит атрибут mode с любым другим значением или вообще без атрибута mode, тогда все файловые атрибуты с именем в теле этого элемента XML будут удалены, а тело элемента XML будет добавлено в качестве нового файлового атрибута.
Прежде чем элемент XML добавляется в набор атрибутов файла, из него удаляется атрибут mode.

fileLock

Эта операция управляет блокировками файла или директории.

Атрибуты:

• fileName

  имя файла или директории.

• mode

  запрошенная операция: lock (блокировка и продолжение блокировки), unlock (разблокирование), testlock (чтение списка блокировок, может использоваться как пустая операция).

• scope

  атрибут используется для постановки блока и задаёт его область: exclusive (исключительная) или shared (разделяемая).

• type

  атрибут используется для постановки блока и задаёт его тип (read, write и т.д.).

• token

  атрибут используется для операций продолжения и снятия блокировки и указывает на дескриптор блокировки, ранее полученный клиентом. Блокировка, принадлежащая владельцу (owner) с указанным дескриптором (token), обновляется или удаляется.

• timeTill

  атрибут используется для операций создания и обновления блокировки и задаёт время окончания блокировки (в выбранном часовом поясе). Если он не указан, то используется время прекращения по умолчанию.

• create

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

Тело:

для операций блокировки - элемент XML owner, содержащий информацию о владельце блокировки. Если операция заканчивается успешно, то сервер отправляет сообщение с данными fileLockData.

fileSubList

Эта операция заставляет Сервер отправить сообщение данных fileSubscription для каждого элемента из набора подписки на файлы Пользователя. Заметьте, что перечисленные в этом наборе файлы могут и не существовать.

fileSubUpdate

Эта операция изменяет набор подписки на файлы Пользователя.

Тело:

набор элементов fileSubscription.

Атрибуты:

• fileName

  имя файла в кодировке UTF-8.

• mode

  если значением этого атрибута является add, то имя fileName добавляется в набор подписки на файлы (за исключением случая, когда в наборе уже имеется файл с таким именем). в противном случае, имя fileName удаляется из набора подписки на файлы.

Сервер присылает следующие сообщения с данными:

fileInfo

Это синхронное сообщение с данными присылается, когда Сервер обрабатывает запрос fileList.

Атрибуты:

• fileName

  имя файла или поддиректории.

• directory

  необязательный атрибут, аналогично атрибуту directory в запросе fileList.

• type

  необязательный атрибут, существует и содержит значение directory, если это сообщение описывает поддиректорию.

• size

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

• timeModified

  необязательный атрибут, в котором находится дата и время изменения файла (местное время, если в запросе не указан атрибут gmtTime).

• timeAttrModified

  необязательный атрибут, в котором находится дата и время изменения атрибутов файла (местное время, если в запросе не указан атрибут gmtTime). Если атрибут fileName был указан в запросе fileList, или указанное в атрибуте directory имя принадлежит обычному файлу, а не директории, то атрибут directory не добавляется в сообщение fileInfo, а атрибут fileName содержит полный путь до файла или директории.

fileDirInfo

Это синхронное сообщение данных отправляется, когда Сервер обрабатывает запрос fileDirInfo.

Обратите внимание

Все атрибуты необязательны, они не существуют, если Сервер не поддерживает их (например, для операций в виртуальной директории хранилища $DomainPBXApp$).

Атрибуты:

• directory

  необязательный атрибут, аналогично атрибуту directory в запросе fileDirInfo.

• files

  общее число файлов Пользователя или в указанной поддиректории (и во всех вложенных директориях).

• size

  общий размер всех файлов (в байтах).

• filesLimit

  ограничение на общее количество фалов (квота) в Установках Пользователя.

• sizeLimit

  ограничение на общий размер фалов (дисковая квота) в Установках Пользователя.

fileDirName

Это синхронное сообщение с данными присылается, когда Сервер обрабатывает запрос fileDirList.

Атрибуты:

• directory

  имя директории в Хранилище Файлов.

fileData

Это синхронное сообщение с данными отправляется, когда Сервер обрабатывает запрос fileRead.

Атрибуты:

• fileName

  имя файла.

• position

  позиция начала прочитанных данных в файле.

• slice

  размер прочитанных данных (в байтах). Чтобы получить следующую порцию данных из файла, новое значение атрибута position складывается из значений атрибутов position и slice.

• size

  общий размер файла.

• timeModified

  необязательный атрибут, в котором находится дата и время изменения файла (местное время).

• type

  копия атрибута type из запроса.

Тело:

Или текст с данными файла, или base64 (телом являются данные в кодировке base64), или представление XML содержимого файла с Объектом.

Примеры:

C:<fileRead id="A001" fileName="test.txt" />
S:<fileData id="A001" fileName="test.txt"position="0" slice="22" size="22" timeModified="20061018T115836">This is not your file!</fileData>
S:<response id="A001"/>

C:<fileRead id="A002" fileName="test.txt" limit="15" />
S:<fileData id="A002" fileName="test.txt"position="0" slice="15" size="22" timeModified="20061018T115836">This is not you</fileData>
S:<response id="A002"/>

C:<fileRead id="A003" fileName="test.txt" limit="15" position="15" />
S:<fileData id="A003" fileName="test.txt"position="15" slice="7" size="22" timeModified="20061018T115836">r file!</fileData>
S:<response id="A003"/>

C:<fileRead id="A004" fileName="test.txt" limit="15" position="15" type="binary" />
S:<fileData id="A004" fileName="test.txt"position="15" slice="7" size="22" timeModified="20061018T115836"><base64>ciBmaWxlIQ==</base64></fileData>
S:<response id="A004"/>

C:<fileRead id="A005" fileName="test.txt" position="25" />
S:<response id="A005" errorText="reading beyond the EOF mark" errorNum="500" />

fileAttrData

Это синхронное сообщение с данными присылается, когда Сервер обрабатывает запрос fileAttrRead.

Атрибуты:

• fileName

  имя файла или директории.

• Тело:

  набор элементов XML с атрибутами.

fileLockData

Эти сообщения с данными отправляются при обработке запроса fileLock.

Атрибуты:

• fileName

  имя файла в кодировке UTF-8.

• token

  строка дескриптора новой или обновлённой блокировки.

• expires

  время прекращения новой или обновлённой блокировки.

• create

  этот атрибут добавляется, когда в результате запроса fileLock создаётся новый пустой файл.

• Тело:

  набор элементов XML fileLockData для всех существующих блокировок.
  Каждый элемент содержит описанные выше атрибуты expires, scope, type.
  Тело сообщения содержит элемент XML owner с информацией о владельце блокировки.

fileSubscription

Эти сообщения с данными отправляются при обработке запроса fileSubList.

Атрибуты:

• fileName

  имя файла в кодировке UTF-8.

Управление Автоматическими Правилами

Клиент может работать с Автоматическими Правилами Пользователя.

rule

Каждое правило представляется в виде элемента XML. Наборы Правил адресуются с использованием параметра type. Поддерживаются следующие значения параметров:

• mailIn - входящие почтовые Правила (Правила Очереди).
• signalIn - входящие Правила Сигналов.

Каждое Правило в наборе имеет атрибуты с именем и приоритетом. Правила Сигналов также имеют атрибут stage, указывающий, когда должно применяться Правило.

Каждое Правило содержит ноль или более элементов condition, ноль или более элементов action и ноль или один элемент comment:

• condition

  Дополнительную информацию смотрите в разделе Правила.

  Атрибуты:

• opCode

  данные условия Правила.

  • operator

    операция условия Правила.

  • Тело:

  параметр условия Правила.

• action

  Дополнительную информацию смотрите в разделе Правила.

  Атрибуты:

  • opCode

    операция действия Правила.

  • Тело:

  параметр действия Правила.

• comment

  • Тело: текст комментария к Правилу.

Пример:
Почтовое Правило, сохраняющее все сообщения с заголовком X-Junk: 5 в Папку Junk. Исключение сделано для сообщений, приходящих от аутентифицированных пользователей.

<rule type="mailIn" name="Junk Filter" priority="2" >
  <condition opCode="Header Field" operator="is">X-Junk: 5*</condition>
  <condition opCode="Source" operator="is not">authenticated</condition>
  <action opCode="Store in">Junk</action>
  <action opCode="Discard"></action>
  <comment>This is my test Rule&#x21;</comment>
</rule>

ruleList

Эта операция предписывает Серверу отправить сообщение rule для каждого Правила указанного типа, существующего у Пользователя. Эти сообщения не имеют тела.

Атрибуты:

• type

  набор Правил.

ruleRead

Эта операция предписывает серверу отправить одно сообщение rule для указанного Правила. В теле этого сообщения содержатся элементы XML с условиями и действиями Правил и необязательный комментарий.

Атрибуты:

• type

  набор Правил.

• name

  имя Правила.

ruleSet

Эта операция сохраняет новое Правило. Если уже есть Правило с таким же именем, то оно удаляется.
Пользователь должен иметь право указывать условия и действия, используемые как в новых, так и в старых Правилах.

Атрибуты:

• type

  набор Правил.

• name

  имя Правила.

• priority

  приоритет Правила.

• stage

  стадия применения Правила (для Правил Сигналов).

Тело:

аналогично элементам XML, используемым в сообщении rule: ноль или более элементов condition, ноль или более элементов action и ноль или один элемент comment.

ruleUpdate

Эта операция изменяет приоритет Правила и/или его стадию применения (для Правил Сигналов).
Пользователь должен иметь право указывать условия и действия, используемые в изменяемом Правиле.

Атрибуты:

• type

  набор Правил.

• name

  имя Правила.

• priority

  приоритет Правила.

• stage

  стадия применения Правила (для Правил Сигналов).

ruleRename

Эта операция переименовывает существующее Правило.
Пользователь должен иметь право указывать условия и действия, используемые в переименовываемом Правиле.

Атрибуты:

• type

  набор Правил.

• name

  имя существующего Правила.

• newName

  новое имя Правила.

ruleRemove

Эта операция удаляет существующее Правило.
Пользователь должен иметь право указывать условия и действия, используемые в удаляемом Правиле.

Атрибуты:

• type

  набор Правил.

• name

  имя существующего Правила.

Сервер присылает следующие сообщения с данными:

rule

Это синхронное сообщение данных отправляется, когда Сервер обрабатывает запрос ruleList или ruleRead. Смотрите выше формат сообщения rule.

Управление записями RPOP, RIMAP и RSIP

Клиент может управлять записями RPOP/RIMAP Пользователя.

rpopRecord

RPOP записи представляются следующими элементами XML:

Атрибуты:

• name

  имя записи.

Тело:

представление XML словаря Записи RPOP.

rpopList

Эта операция предписывает Серверу отправить одно сообщение rpopRecord для каждой записи RPOP Пользователя.

Атрибуты:

• отсутствуют

rpopUpdate

Эта операция обновляет набор записей RPOP Пользователя.
Пользователь должен иметь право изменять записи RPOP.

Атрибуты:

• отсутствуют

Тело:

один или несколько элементов rpopRecord. Эти элементы должны иметь дополнительный атрибут:

• mode

  если значением этого атрибута является delete, то используется только атрибут name. Указанная запись RPOP удаляется из набора записей RPOP Пользователя.
  Иначе, запись RPOP из тела элемента rpopRecord добавляется в набор записей RPOP пользователя; Если запись с таким же именем уже была в наборе, то она удаляется.

rimapRecord

RIMAP записи представляются следующими элементами XML:

Атрибуты:

• name

  имя записи.

Тело:

представление XML словаря Записи RIMAP.

rimapList

Эта операция предписывает Серверу отправить одно сообщение rimapRecord для каждой записи RIMAP Пользователя.

Атрибуты:

• отсутствуют

rimapUpdate

Эта операция обновляет набор записей RIMAP Пользователя.
Пользователь должен иметь право изменять записи RIMAP.

Атрибуты:

• отсутствуют

Тело:

один или несколько элементов rimapRecord. Эти элементы должны иметь дополнительный атрибут:

• mode

  если значением этого атрибута является delete, то используется только атрибут name. Указанная запись RIMAP удаляется из набора записей RIMAP Пользователя. Иначе, запись RIMAP из тела элемента rimapRecord добавляется в набор записей RIMAP пользователя; Если запись с таким же именем уже была в наборе, то она удаляется.

Записи RSIP представляются элементами XML rsipRecord:

Атрибуты:

• name

  имя записи.

• Тело:

представление XML словаря Записи RSIP.

Клиент может управлять записями RSIP Пользователя.

rsipList

Эта операция предписывает Серверу отправить одно сообщение rsipRecord для каждой записи RSIP Пользователя.

Атрибуты:

• отсутствуют

rsipUpdate

Эта операция обновляет набор RSIP записей Пользователя.
Пользователь должен иметь право изменять записи RSIP.

Атрибуты:

• отсутствуют

Тело:

один или несколько элементов rsipRecord. Эти элементы должны иметь дополнительный атрибут:

• mode

  если значением этого атрибута является delete, то используется только атрибут name. Запись RSIP с таким же атрибутом name удаляется из набора записей RSIP Пользователя.
  Иначе, запись RSIP из тела элемента rsipRecord добавляется в набор записей RSIP пользователя; если запись с таким же именем уже была в наборе, то она удаляется.

Сервер присылает следующие сообщения с данными:

rpopRecord

Это синхронное сообщение данных присылается, когда Сервер обрабатывает запрос rpopList. Смотрите формат сообщения rpopRecord.
Необязательный атрибут timeCompleted показывает время (в выбранном часовом поясе) последней попытки соединения.
Если последняя попытка опроса учётной записи RPOP была неудачной, в записи содержится дополнительный атрибут errorText со строкой сообщения об ошибке.

rimapRecord

Это синхронное сообщение данных присылается, когда Сервер обрабатывает запрос rimapList. Смотрите формат сообщения rimapRecord. Необязательный атрибут timeCompleted показывает время (в выбранном часовом поясе) последней попытки соединения.
Если последняя попытка опроса учётной записи RIMAP была неудачной, в записи содержится дополнительный атрибут errorText со строкой сообщения об ошибке.

rsipRecord

Это синхронное сообщение с данными отправляется, когда Сервер обрабатывает запрос rsipList. Смотрите формат сообщения rsipRecord.
Необязательный атрибут timeCompleted показывает время (в выбранном часовом поясе) последней попытки соединения.
Если последняя попытка регистрации с учётной записью RSIP была неудачной, в записи содержится дополнительный атрибут errorText со строкой сообщения об ошибке.

Управление Приложениями Реального Времени

Клиент может взаимодействовать с Приложениями Реального Времени, запущенными на Сервере или в Кластере CommuniGate Pro.

Сессия XIMSS может взаимодействовать с Задачами, отправляя им События. Задачи воспринимают сессию XIMSS просто как другую Задачу, так что они также могут отправлять обратно События.

Каждая сессия XIMSS поддерживает список Дескрипторов Задач для тех Задач, с которыми она взаимодействует. Каждый дескриптор в списке связан со строкой taskID. XIMSS клиент использует эти строки taskID для нахождения Задачи в списке.

taskFindMeeting

Этот запрос реализует операцию FindMeeting. Дополнительную информацию смотрите в разделе CG/PL.

Атрибуты:

• meetingSet

  необязательное имя набора Встреч. Если значение этого параметра опущено или является пустой строкой, то используется Набор Встреч, применяемый по умолчанию.

• meetingName

  уникальный идентификатор Встречи. Если эта операция заканчивается успешно, то Сервер возвращает сообщение taskMeeting с обнаруженными данными встречи.

taskCreateMeeting

Этот запрос реализует операцию CreateMeeting. Дополнительную информацию смотрите в разделе CG/PL.

Атрибуты:

• meetingSet

  необязательное имя набора Встреч. Если значение этого параметра опущено или является пустой строкой, то используется Набор Встреч, применяемый по умолчанию.

• meetingName

  уникальный идентификатор Встречи.

Тело:

Текст, добавляемый в Событие Встречи в качестве параметра.

• taskRemoveMeeting, taskClearMeeting, taskActivateMeeting, taskDeactivateMeeting

  Эти запросы реализуют операции для объектов Встреч. Дополнительную информацию смотрите в разделе CG/PL.

  Атрибуты:

  • meetingSet

    необязательное имя набора Встреч. Если значение этого параметра опущено или является пустой строкой, то используется Набор Встреч, применяемый по умолчанию.

  • meetingName

    уникальный идентификатор Встречи.

taskSendEvent

Эта операция отправляет Задаче Событие.

Атрибуты:

• taskRef

  внутренний taskID Задачи, который отправляется Событие.

• eventName

  имя отправляемого События.

Тело:

необязательный текст или представление XML объекта данных, которые будут отправлены как параметр События.

taskStart

Эта операция запускает Задачу Приложения Реального Времени.
Если операция заканчивается успешно, то сервер отправляет сообщение данных taskCreated.

Атрибуты:

• programName

  имя приложения.

• entryName

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

Тело:

набор элементов XML param. Текстовые тела этих элементов помещаются в массив startParameter Задачи.

taskClose

С каждым внутренним taskID связываются некоторые определённые ресурсы сессии. Если клиент работает со многими задачами, то по завершению взаимодействия с какой-либо Задачей рекомендуется использование операции taskClose, что освобождает все внутренние ресурсы taskID.
Если та же Задача отправляет в эту сессию Событие или Описатель Задачи был обнаружен другим способов, то в этой сессии этой Задаче присваивается новый taskID.

Атрибуты:

• taskRef

  освобождаемый внутренний taskID.

Сервер присылает следующие сообщения с данными:

taskMeeting

Это синхронное сообщение данных отправляется, когда Сервер обрабатывает запрос taskFindMeeting.

Атрибуты:

• meetingSet, meetingName

  копия атрибутов запроса taskFindMeeting.

• taskRef

  необязательный атрибут: внутренний taskID Задачи, который активировал эту Встречу.

• expires

  необязательный атрибут с датой и временем (GMT) прекращения доступности Встречи.

• Тело:

Представление XML параметров Встречи.

taskCreated

Это синхронное сообщение с данными отправляется, когда Сервер обрабатывает запрос taskStart.

• Атрибуты:

• taskRef

  внутренний taskID созданной Задачи.

taskEvent

Это асинхронное сообщение с данными присылается, когда некоторая Задача или сам Сервер отправляет Событие в текущую сессию XIMSS.

• Атрибуты:

• taskRef

  внутренний taskID Задачи, отправившей Событие. Если этот атрибут отсутствует, то Событие было создано и отправлено самим Сервером.

• eventName

  имя полученного События.

• Тело:

Текст или представление XML параметров События.

Справочник

Клиент может получать доступ к глобальному Справочнику.

listDirectory

Эта операция получает данные из Справочника.

Атрибуты:

• baseDN

  DN записи Справочника, с которой начинается поиск. Если значением атрибута является $, то baseDN устанавливается в то поддерево Справочника, в котором содержатся записи для текущего Домена Пользователя.

• filter

  этот необязательный атрибут задаёт фильтр поиска в формате RFC2254.

• scope

  в этом необязательном атрибуте задаётся тип поиска:

  • base - baseDN получаемой записи (атрибут filter игнорируется)
  • one (по умолчанию) - поиск осуществляется непосредственно в поддереве baseDN (одноуровневый поиск)
  • sub - поиск осуществляется во всём поддереве baseDN (многоуровневый поиск)

• limit

  в этом необязательном атрибуте задаётся максимальное количество записей в результате поиска.

• sortField

  в этом необязательном атрибуте задаётся список имён атрибутов через запятую, которые используются для сортировки записей.

  Обратите внимание

  Атрибуты ближе к концу списка имеют больший вес при сортировке.

• sortOrder

  если этот необязательный атрибут задан и имеет значение desc, то применяется обратный порядок сортировки.

• cookie

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

• Тело (необязательно):

набор элементов XML field. Каждый элемент должен иметь текстовое тело, содержащее имя получаемого атрибута. Если элемент field не указан, то возвращаются все неслужебные атрибуты записи Справочника.

Обратите внимание

Если атрибут mail указан явно, то Сервер сформирует значение этого атрибута для всех записей объектов CommuniGate Pro, у которых он отсутствует. Сервер присылает сообщение directoryData для каждой найденной записи.

modifyDirectory

Эта операция изменяет данные в Справочнике.

Атрибуты:

• name

  DN записи Справочника, которая будет изменена. Символ $ заменяется на строку значения поддерева Справочника, в котором содержатся записи для текущего Домена Пользователя.

• newName

  если этот необязательный атрибут задан, то DN записи будет переименовано.

Тело (необязательно):

Представление XML атрибутов записи Справочника.
Если Тело пустое и отсутствует атрибут newName, то запись с данным DN будет удалена. Пример:

C:<modifyDirectory id="A001" name="mail=user@example.dom,$">
C: <subKey key="mail">user@example.dom</subKey>
C: <subKey key="cn">User J. Smith</subKey>
C: <subKey key="sn"></subKey>
C: <subKey key="objectclass">
C:  <subValue>top</subValue>
C:  <subValue>person</subValue>
C:  <subValue>organizationalPerson</subValue>
C:  <subValue>inetOrgPerson</subValue>
C: </subKey>
C:</modifyDirectory>
S:<response id="A001"/>

Сервер присылает следующие сообщения с данными:

directoryData

Это синхронное сообщение данных отправляется для каждой записи Справочника, возвращаемой в ответ на запрос listDirectory.

Атрибуты:

• name

  DN записи.

• cookie

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

Тело:

Представление XML атрибутов Записи.

Наборы Данных

Клиент может управлять наборами данных Пользователя - например, такими, как набор данных RepliedAddresses (авто-отвеченные).

Для доступа к Набору данных другого Пользователя, имя набора данных должно быть задано как ~accountName/datasetName или ~accountName@domainName/datasetName

datasetCreate

Эта операция создаёт набор данных Пользователя.

Атрибуты:

• dataset

  имя создаваемого набора данных.

datasetRemove

Эта операция удаляет набор данных Пользователя.

Атрибуты:

• dataset

  имя удаляемого набора данных.

• ifExists

  если значением этого необязательного атрибута является yes и набор данных не существует, то сообщение об ошибке не создаётся.

datasetAddAddress

Эта операция добавляет адрес в набор данных Пользователя.

Атрибуты:

• dataset

  имя набора данных, в который будет добавлен адрес электронной почты.

• realName

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

• Тело:

Строка с адресом электронной почты.

datasetList

Эта операция получает данные из набора данных Пользователя.

Атрибуты:

• dataset

  имя набора данных.

• filterField, filter

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

• mode

  этот необязательный атрибут может быть указан, если указан атрибут filterField.
  Если атрибут mode отсутствует или его значение равно eq, то запись попадает в результат если указанный атрибут имеет указанное значение.
  Если значение атрибута mode равно beg, то запись попадает в результат, если значение указанного атрибута начинается с указанного значения.
  Если значение атрибута mode равно end, то запись попадает в результат, если значение указанного атрибута оканчивается указанным значением.
  Если значение атрибута mode равно contains, то запись попадает в результат, если в значении указанного атрибута содержится указанное значение. Сервер отправляет сообщение datasetData для каждой найденной записи.

datasetListSubsets

Операция перечисляет все разделы Набора Данных Пользователя.

Атрибуты:

• dataset

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

datasetSet

Эта операция изменяет записи в наборе данных Пользователя.

Атрибуты:

• dataset

  имя изменяемого набора данных.

• Тело:

Элемент datasetData. Его атрибут name задаёт имя записи из набора данных, которую необходимо изменить или создать. Если он не указан, то для новой записи генерируется случайно имя.
Телом элемента должно быть представление XML изменяемых атрибутов данных.

datasetDelete

Эта операция удаляет запись из набора данных Пользователя.

Атрибуты:

• dataset

  имя изменяемого набора данных.

• name

  имя записи, удаляемой из набора данных.

Сервер присылает следующие сообщения с данными:

datasetData

Это синхронное сообщение с данными присылается для каждой записи из набора данных, возвращаемой в ответ на запрос datasetList.

Атрибуты:

• name

  имя записи из набора данных.

Тело:

Представление XML атрибутов записи из набора данных.

datasetSubset

Это синхронное сообщение с данными присылается для каждого раздела из набора данных в ответ на запрос datasetListSubsets.

Атрибуты:

• dataset

  имя записи в разделе.

• Тело:

отсутствует

Тарификация

Клиент может работать со средствами на балансовых Остатках Пользователя.

balance

Эта операция выполняет операцию Тарификации.

Атрибуты:

• accountName

  имя Пользователя (необязательно). Если не указано, то операция применяется для Пользователя, которому принадлежит данная сессия.

• localTime

  если атрибут не указан или указан со значением иным, чем no, все значения атрибутов с отметкой времени должны быть указаны с использованием часового пояса из настроек Пользователя; результаты также используют этот часовой пояс.
  Если значение равно no, все значения атрибутов с отметкой времени в запросах и результатах используют часовой пояс GMT.

• Тело:

  Представление XML словаря. Словарь содержит тип операции Тарификации (элемент op) и параметры самой операции. Если операция генерирует какой-либо результат, то сервер возвращает сообщение balanceData.

Сервер присылает следующие сообщения с данными:

balanceData

Это синхронное сообщение с данными присылается, когда операция balance выдаёт какой-либо результат.

Атрибуты:

• accountName

  имя целевого пользователя (необязательно, аналогично указанному в запросе операции balance).

Тело:

Словарь с результатами в представлении XML.

Помощники Приложений

Клиент может вызывать Помощники Приложений.

callHelper

Эта операция вызывает Помощник Приложений. Если операция генерирует какой-либо результат, то сервер возвращает сообщение helperReply.

Атрибуты:

• name

  имя Помощника Приложений.

• mode

  необязательная строка для указания члена кластера с запущенным Помощником Приложений.

Тело:

(необязательно) представление XML для параметров запроса к Помощнику.

Сервер присылает следующие сообщения с данными:

helperReply

Это синхронное сообщение данных отправляется, когда операция callHelper генерирует какой-либо результат.

Атрибуты:

• name

  имеет то же значение, что и в операции callHelper.

• Тело:

(необязательно) представление XML для возвращаемых данных от Помощника.

Получение Рекламы

Клиент может задействовать Внешнюю Рекламную Систему.

bannerRead

Эта операция получает рекламную информацию. Если операция генерирует какой-либо результат, то сервер возвращает сообщение banner.

Атрибуты:

• type

  тип получаемой рекламы (зависит от приложения, например, prontoEmailTop, myClientLeftBanner).

• Тело:

(необязательно) представление XML для параметров объекта из Внешней Рекламной Системы.

Сервер присылает следующие сообщения с данными:

banner

Это синхронное сообщение данных отправляется, когда операция bannerRead генерирует какой-либо результат.

Атрибуты:

• type

  имеет то же значение, что и в операции bannerRead.

Тело:

(необязательно) представление XML для результирующего объекта из Внешней Рекламной Системы.

Синхронные Скрипты

Клиент может использовать Синхронные Скрипты, расположенные на сервере.

runScript

Эта операция выполняет на сервере синхронный скрипт. В ответ сервер шлёт сообщение scriptResult.

Атрибуты:

• fileName

  имя файла с синхронным скриптом (суффикс .scgp использовать не обязательно).

• name

  (необязательно) имя точки входа в скрипт.

Тело:

(необязательно) объект-параметр в представлении XML.

Сервер присылает следующие сообщения с данными:

scriptResult

Это синхронное сообщение данных отправляется, когда операция runScript генерирует результат.

• Атрибуты:
• Тело:

(необязательно) объект-результат в представлении XML.

Форматы Данных XML

Элементы данных представляются в формате XML с использованием следующих соглашений.

EMail

Этот элемент XML представляет сообщение электронной почты или его раздел MIME в соответствии с RFC822.

• Тело:

  набор элементов XML, содержащих поля заголовка сообщения электронной почты, такие как From, Date и т.д., не включая поля MIME, связанные с содержимым (такие как Content-Type),
  и (необязательно) элемент MIME с телом сообщения.

  Типом каждого XML элемента является имя поля, например:

  `<Subject>Hello, world!</Subject>`
  

  Категории полей:

  • Адреса: From, To, Cc, Bcc, Return-Path, Sender, Reply-To, Disposition-Notification-To, Recent-From, Recent-To, Return-Receipt-To, Errors-To

    Телом элемента является адрес электронной почты в формате userName@domainName или в более общем формате userName[%domainA[%domainB]]@domainName.
    Эти элементы могут содержать атрибут realName - декодированные из MIME части имени или комментарий адреса.
    Если поле содержит несколько адресов, то создаётся несколько XML элементов, так, что каждый элемент содержит ровно один адрес.

  • Отметки времени: Date, Resent-Date

    Эти элементы содержат:
    атрибут timeShift - разница в секундах между местным временем, указанным в поле, и соответствующим GMT временем.
    атрибут localTime, указывающий значение времени поля (в формате iCalendar) в часовом поясе, выбранном для текущего пользователя.
    Телом элемента является глобальное значение времени поля (GMT) в формате iCalendar.

  • Pty

    Телом этих элементов являются строки High или Low. Эти значения преобразовываются в числовые значения (и из числовых значений) поля заголовка X-Priority.

  • Phones: X-Telnum

    Тело элемента является телефонным номером.
    Эти элементы могут содержать атрибут type (WORK, CELL, HOME, AGENT и т.п.), указывающий на тип телефонного номера/адреса.
    Если поле содержит несколько телефонных номеров, то создаётся несколько XML элементов, так, что каждый элемент содержит ровно один телефонный номер.

  • Unstructured Все поля, не перечисленные в предыдущих категориях, относятся к этой категории. Тело элемента содержит декодированное из MIME значение поля.

Пример:

From: "Mr. Sender." <user1@example.com>
To: user2@example.com (My Friend),
 =?iso-8859-1?Q?=4Eot=20A=20Friend?= <user2@example.com>
Date: Mon, 10 Apr 2006 13:15:48 -0700
Subject: It's 1:15PM now, the meeting has started!

<EMail>
  <From realName="Mr. Sender.">user1@example.com</From>
  <To realName="My Friend">user2@example.com</To>
  <To realName="Not A Friend">user3@example.com</To>
  <Bcc>user1@example.com</Bcc>
  <Date timeShift="-25200" localTime="20060410T151548">20060410T201548Z</Date>
  <Subject>It's 1:15PM now, the meeting has started!</Subject>
</EMail>

MIME

XML элемент представляет тело сообщения или его часть (далее в этом разделе - "часть").

Атрибуты:

• partID

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

• estimatedSize

  ориентировочный размер (в байтах) данных части, после декодирования её данных.

• type

  тип части Content-Type, без информации о подтипе.

• subtype

  подтип части Content-Type, если есть.

• charset

  кодировка части (если отсутствует, то подразумевается UTF-8).

• contentID

  строка Content-ID (не заключённая в угловые скобки).

• disposition

  строка Content-Disposition (без параметров).

• description

  строка Content-Description.

• location

  строка Content-Location.

• class

  строка Content-Class после удаления префиксов urn: и content-classes:.

• Type-name

  любой параметр name поля Content-Type и его значение, за исключением параметров boundary, charset и format.

• Disposition-name

  любой параметр name поля Content-Disposition и его значение.

Тело:

Тело элемента не является обязательным. Если оно присутствует, оно содержит данные тела части.
Если Сервер не смог прочитать данные тела части элемента, то к элементу добавляется атрибут readError. Значение атрибута содержит код ошибки чтения.
Если Сервер не смог разобрать данные тела части элемента, то к элементу добавляется атрибут parseError. Значение атрибута содержит код ошибки разбора.
Формат элемента зависит от части Content-Type (символ "*" ниже обозначает любой Content-Type или подтип):

• multipart/*

  Ноль или более элементов XML MIME, в которых содержатся подчасти сообщения.

• message/rfc822

  Элемент XML EMail для вложенного сообщения.

• text/rfc822-headers

  Элемент XML EMail (не содержащий никакого элемента тела MIME).

• text/directory, text/x-vcard

  Ноль или более элементов XML vCard.

• text/x-vgroup

  Один элемент XML vCardGroup.

• text/calendar

  элемент XML iCalendar.

• message/disposition-notification, message/delivery-status

  элемент XML MIMEReport.

• */xml, */*+xml

  Данные XML элемента тела.

• text/*

  Декодированный текст сообщения, в котором все символы конца строки заменены на символ Перевода Строки (0x0A).

  Обратите внимание

  Когда присылается сообщение, запрошенное операцией folderRead, тело элемента MIME включается только если:

• его Content-Type - один из поддерживаемых типов, перечисленных выше

• его Content-Disposition не равен attachment

• его размер плюс размер частей, уже включённых в данные XML ответа, не превышает значения атрибута запроса totalSizeLimit. :::

Пример:

From: <user1@example.com>
To: user2@example.com
MIME-Version: 1.0
Content-Type: multipart/alternative;boundary="abcd"
Content-Description: Test Message

--abcd
Content-Type: text/plain; charset="iso-8859-1";
format=flowed; paramX="valueX"
Content-Transfer-Encoding: quoted-printable

=46rom where I stay, I can see & hear a lot!

--abcd
Content-Type: text/html; charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

<html><body bgcolor=3D"yellow">
<I>From where I stay</I>, I can see &amp; hear a lot!
</body></html>
--abcd--

<EMail>
  <From>user1@example.com</From>
  <To>user2@example.com</To>
  <MIME Type="multipart" subtype="alternative" Description="Test Message">
    <MIME type="text" subtype="plain" charset="iso-8859-1" type-paramX="valueX">
      From where I stay, I can see &amp; hear a lot!
    </MIME>
    <MIME type="text" subtype="html" charset="iso-8859-1" type-paramX="valueX">
    &lt;html&gt;&lt;body bgcolor=&quot;yellow&quot;&gt;
    &lt;I&gt;From where I stay&lt;/I&gt;, I can see &amp;amp; hear a lot!
    &lt;/body&gt;&lt;/html&gt;
    </MIME>
  </MIME>
</EMail>

MIMEReport

Этот элемент XML элемент представляет сообщение с отчётом, таким как Оповещение об Открытии (Disposition Notification) или Отчёт о Доставке.

Атрибуты:

отсутствуют

Тело:

набор элементов XML, в которых содержатся поля заголовка отчёта, такие как Reporting-MTA, Final-Recipient и т.п.
а также (необязательно) элементы MIMEReport для тела отчёта.

Пример:

Subject: Delivery report: TEST - disposition and delivery
From: <MAILER-DAEMON@remote.example.com>
To: <sender@local.example.com>
Date: Wed, 02 May 2007 00:33:13 -0700
Message-ID: <receipt-39457791@remote.example.com>
X-MAPI-Message-Class: REPORT.IPM.Note.DR
MIME-Version: 1.0
Content-Type: multipart/report; report-type="delivery-status"; boundary="_===39457791====remote.example.com===_"


--_===39457791====remote.example.com===_
Content-Type: text/plain; charset="utf-8"

Message delivered to '<recepient@remote.example.com>'
LOCAL module(account recepient) reports:
Delivered to the user mailbox


--_===39457791====remote.example.com===_
Content-Type: message/delivery-status

Reporting-MTA: dns; remote.example.com

Original-Recipient: rfc822;<recepient@remote.example.com>
Final-Recipient: LOCAL;<recepient>
Action: delivered
Status: 2.0.0

--_===39457791====remote.example.com===_
Content-Type: text/rfc822-headers

From: "Sender Name" <sender@local.example.com>
Subject: TEST - disposition and delivery
To: recepient@remote.example.com
X-Mailer: CommuniGate Pro WebUser v5.1.9
Date: Wed, 02 May 2007 00:35:51 -0700
Message-ID: <web-3990004@local.example.com>
MIME-Version: 1.0
Disposition-Notification-To: <sender@local.example.com>
Content-Type: text/plain;charset="utf-8";format="flowed"
Content-Transfer-Encoding: 8bit

--_===39457791====remote.example.com===_--

<EMail>
 <Subject>Delivery report: TEST - disposition and delivery</Subject>
 <From>MAILER-DAEMON@communigatepro.ru</From>
 <To>sender@local.example.com</To>
 <Date localTime="20070502T003313" timeShift="-25200">20070502T073313Z</Date>
 <Message-ID>&lt;receipt-39457791@remote.example.com&gt;</Message-ID>
 <X-MAPI-Message-Class>REPORT.IPM.Note.DR</X-MAPI-Message-Class>
 <MIME estimatedSize="1433" subtype="report" type="multipart" Type-report-type="delivery-status">
  <MIME charset="utf-8" estimatedSize="120" partID="01" subtype="plain" type="text">Message delivered to &#39;&lt;recepient@remote.example.com&gt;&#39;
LOCAL module(account recepient) reports:
 Delivered to the user mailbox

  </MIME>
  <MIME estimatedSize="158" partID="02" subtype="delivery-status" type="message">
   <MIMEReport>
    <Reporting-MTA>dns; remote.example.com</Reporting-MTA>
    <MIMEReport>
     <Original-Recipient>rfc822;&lt;recepient@remote.example.com&gt;</Original-Recipient>
     <Final-Recipient>LOCAL;&lt;recepient&gt;</Final-Recipient>
     <Action>delivered</Action>
     <Status>2.0.0</Status>
    </MIMEReport>
   </MIMEReport>
  </MIME>
  <MIME estimatedSize="787" partID="03" subtype="rfc822-headers" type="text">
   <EMail>
    <From realName="Sender Name">sender@local.example.com</From>
    <Subject>TEST - disposition and delivery</Subject>
    <To>recepient@remote.example.com</To>
    <X-Mailer>CommuniGate Pro WebUser v5.1.9</X-Mailer>
    <Date localTime="20070502T003551" timeShift="-25200">20070502T073551Z</Date>
    <Message-ID>&lt;web-3990004@local.example.com&gt;</Message-ID>
    <Disposition-Notification-To>sender@local.example.com</Disposition-Notification-To>
   </EMail>
  </MIME>
 </MIME>
</EMail>

Доступ по протоколу HTTP

Некоторые клиенты могут не поддерживать выполнение всех операций через протокол XIMSS. При создании сессии XIMSS, её идентификатор направляется клиенту обратно в сообщении с данными session. Сервер обеспечивает доступ к этой сессии через протокол HTTP.

Получение Части Сообщения

Для получения любой части сообщения, видимого в любом текущем открытом представлении Папки может использоваться следующий URL: /Session/sessionID/MIME/folder/UID-partID-suffix[/filename], где

• sessionID

  идентификатор текущей сессии XIMSS, присланный в сообщении с данными session.

• folder

  имя Представления папки или Календаря

• UID

  UID сообщения в Представлении папки или в Календаре.

• partID

  идентификатор запрашиваемой части MIME сообщения. Это строка в элементе XML MIME при получении сообщения с использованием операции folderRead. Если необходимо получить всё сообщение, то строка partID и следующий за ней символ - должны быть опущены.

• suffix

  режим получения:

  • P.txt - получается полностью недекодированная часть (включая заголовки и тело).
  • H.txt - получается часть с заголовками.
  • B.extension - получается тело декодированной части. Вы можете использовать любое подходящее расширение имени файла. Ответ на запрос HTTP содержит Content-Type полученной части MIME.
  • R/cid - строка cid должна быть URI-кодированной. Её декодированное значение указывает Content-ID части MIME. Сервер ищет все части MIME, "связанные" с текущей, и получает тело той части, у которой совпадает Content-ID.
    Эта возможность используется для преобразования URL типа cid: в сообщения в формате HTML.

• filename

  необязательное имя файла. Оно игнорируется сервером, но помогает браузеру пользователя сохранять файл с правильным именем. Примеры:

C:GET /Session/1-2xklkdld8-djdkjk/MIME/INBOX/567-01-B.gif HTTP/1.1

C:GET /Session/1-2xklkdld8-djdkjk/MIME/INBOX/567-02-01-B.gif/Logo.gif HTTP/1.1

Возможно получить только порцию части сообщения при использовании заголовков HTTP Range. Если заголовки запроса не могут быть указаны, возможно использование следующих параметров строки запроса:

• OffsetFrom

  позиция (в байтах) начала порции (0 означает начало части).

• OffsetTill

  (необязательно) позиция (в байтах) байта, следующего за концом запрошенной порции. Пример:

C:GET /Session/1-2xklkdld8-djdkjk/MIME/INBOX/567-01-B.gif?OffsetFrom=100&OffsetTill=200 HTTP/1.1

По этому запросу возвращается 100 байт (100..199 включительно) из файла в формате GIF, закодированного в указанной части MIME сообщения.

Получение данных о Пользователе

С помощью запроса по указанному URL можно получить публичные данные пользователя или любой их атрибут: /Session/sessionID/PROFILE/[propertyname[/index][/filename]], где

• sessionID

  идентификатор текущей сессии XIMSS, присланный в сообщении с данными session.

• propertyname

  имя атрибута vCard, например, PHOTO. Если атрибут не указать, считывается объект vCard целиком.

• index

  если объект vCard содержит несколько значений для указанного атрибута vCard, можно указать порядковый номер (начиная с 0). Значение индекса принимается равным 0, если параметр не указан.

• filename

  любая строка, кодированная как URL. Пример:

C:GET /Session/1-2xklkdld8-djdkjk/PROFILE/PHOTO/0/avatar HTTP/1.1

Этим запросом можно получить значение первого элемента атрибута "PHOTO" из объекта vCard публичных данных Пользователя.

Загрузка Файла на Сервер

Следующий URL может использоваться для загрузки файла на сервер в "набор загруженных файлов" сессии. /Session/sessionID/UPLOAD/uploadID, где

• sessionID

  идентификатор текущей сессии XIMSS, присланный с сообщением данных session.

• uploadID

  строка, идентифицирующая этот файл в "наборе загруженных файлов".

Запрос по протоколу HTTP должен быть сделан:

• методом POST, с содержимым формата multipart/form-data, элемент fileData которого включает бинарное представление загружаемого файла, или
• методом PUT, с бинарным представлением загружаемого файла в теле запроса.

Когда файл загружается на сервер и добавляется к "набору загруженных файлов", Сервер возвращает код ответа 200. Если операция загрузки закончилась неуспешно, Сервер возвращает код ответа 500.

Загруженный файл сохраняется вместе с его значением Content-Type.

Если "загруженный набор файлов" уже содержит файл с заданным значением uploadID, то старый файл удаляется.

Скачивание Файла

Следующий URL может использоваться для скачивания файла из Хранилища Файлов Пользователя сессии. /Session/sessionID/DOWNLOAD/fileName, где

• sessionID

  идентификатор текущей сессии XIMSS, присланный с сообщением данных session.

• fileName

  имя файла в Хранилище Файлов Пользователя.

  Обратите внимание

  Для того, чтобы загрузить файл из "набора загруженных файлов", указывайте fileName как $UPLOAD$/uploadId, где uploadId является идентификатором файла в "наборе загруженных файлов".

Экспортирование данных

Запросом на следующий URL можно экспортировать данные из папки или календаря: /Session/sessionID/Export/folderName/fileName[?oldStyle=1] Если folderName является именем открытого объекта Calendar, запрос извлекает текст в формате iCalendar, включающий все объекты VEVENT и VTODO, со всеми использованными в них объектами VTIMEZONE.
Если folderName является именем открытого Представления Папки, запрос извлекает текст в формате vCard, включающий все объекты vCard из объектов в этом Представлении Папки. При указании параметра oldStyle данные vCard экспортируются в формате vCard 2.1 и кодировке UTF-8, иначе используются формат vCard 3.0 и кодировка Unicode.

Экспортирование Закрытого Ключа и Сертификата

Запросом на следующий URL можно экспортировать Закрытый Ключ и Сертификат Пользователя в формате PKCS12 (файл "PFX"): /Session/sessionID/CertAndKey.pfx?PFXPassword=password[&PFXPassword1=password1] Если указан параметр PFXPassword1, его значение должно быть таким же, как у параметра PFXPassword.
Данные S/MIME в сессии должны быть разблокированы.
Закрытый Ключ и Сертификат Пользователя помещаются файл в формате PKCS12, зашифрованный с помощью значения параметра PFXPassword.

Аварийное прекращение сессии

Следующий URL может использоваться для прекращения сессии без процедур очистки: /Session/sessionID/KILL