Клиент может использовать следующий набор операций для работы с Папками аутентифицированного Пользователя, а также с Папками других Пользователей (указывая полное имя Папки в виде ~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 - используются значения атрибутов метаданных сообщения.
Дополнительную информацию о флагах сообщения в Папке смотрите в разделе Папки.
Сессия может использовать несколько Представлений Папки одновременно.
Клиент должен обслуживать внутренний вид Представления папки - массив или таблицу элементов для каждого сообщения из Представления. Клиент должен держать этот вид синхронизированным с видом Сервера (реализованным в этом Представлении Папки).
При открытии Представления папки Сервер отправляет сообщение с данными 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"/>
- messageCopy
- Эта операция копирует сообщения из открытого Представления папки в целевую Папку.
Обратите внимание: цель является Папкой, а не Представлением папки. - Атрибуты:
- folder
- имя Представления папки - источника.
- targetMailbox
- имя Папки-приёмника.
- mailboxClass
- Если Папка-приёмник не существует и указан этот необязательный атрибут, то Папка-приёмник будет создана. Если значением этого атрибута является непустая строка, то это значение используется как Класс Папки для создаваемой Папки.
- encrypt
- если этот необязательный атрибут задан со значением yes, то все сообщения копируются в зашифрованном виде с использованием S/MIME Сертификата текущего пользователя.
- decrypt
- если этот необязательный атрибут задан и имеет значение yes, а атрибут encrypt не задан, то все сообщения копируются в расшифрованном виде. Закрытый Ключ Пользователя должен быть разблокирован, иначе операция завершится с ошибкой.
- report
- Если этот атрибут задан, то он должен иметь значение uid.
Если сообщение было успешно создано и добавлено в Папку-приёмник, то Сервер отправляет синхронное сообщение messageAdded, содержащее UID нового добавленного сообщения.
Тело:- набор сообщений (смотрите выше).
- messageMove
- Эта операция аналогична операции messageCopy, но если сообщение было скопировано успешно, то операция удаляет оригинальное сообщение.
Эта операция также может быть использована для реализации "шифрования сообщений": выбранные сообщения должны быть передвинуты в ту же Папку с использованием атрибутов encrypt или decrypt.
- messageMark
- Эта операция изменяет флаги сообщения Папки в открытом Представлении папки.
- Атрибуты:
- folder
- имя Представления папки.
- flags
- этот атрибут задаёт добавляемые или удаляемые флаги сообщения Папки. Могут быть указаны несколько операций, отделённые символом запятой. Дополнительную информацию смотрите в разделе Папки.
Тело:- набор сообщений (смотрите выше).
- 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</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>[email protected]</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>[email protected]</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</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>[email protected]</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>[email protected]</From>
<Subject>Shutdown @ 4:45AM</Subject>
</folderReport> S:
<response id="A005" />
- 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>[email protected]</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"/>
Клиент должен использовать операцию "bind" для того, чтобы начать получать сигналы, направляемые аутентифицированному пользователю.
Клиент может обслуживать одну или несколько одновременных коммуникационных сессий ("звонков"). Каждый звонок идентифицируется по его атрибуту callLeg. Атрибут callLeg присутствует во всех запросах клиента и сообщениях сервера, относящихся к звонку. Все звонки независимы друг от друга.
Для каждого звонка клиент должен уметь создать один или несколько "медиа-объектов", которые фактически реализуют медиа сессии заданного типа (аудио, видео и т.д.). Описатели медиа данных ("объекты SDP") - это элементы данных (в виде текста или XML), которыми клиент обменивается со своими "медиа-объектами".
Как минимум, с каждым медиа-объектом должны быть возможны следующие операции:
- получить SDP "предложения" от медиа-объекта, а потом передать ему SDP "ответа", который описывает медиа-объект абонента; или
- передать SDP "предложения", описывающим медиа-объект абонента, а потом получить SDP "ответа".
Если перепосылка SDP с "предложением" уже активному медиа-объекту невозможна, то должен быть создан новый объект, и "предложение" должно быть отправлено ему. Если от нового медиа-объекта был успешно получен SDP с "ответом", то старый медиа-объект должен быть уничтожен.
Если получение SDP с "предложением" от уже активного медиа-объекта невозможно, то должен быть создан новый объект, и "предложение" должно быть получено от него. Когда SDP "ответа" получен и передан новому медиа-объекту, старый медиа-объект должен быть уничтожен.
медиа-объект поддерживает "расщепление" (forking), если от него возможно получить единственное 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.
Когда начинается исходящий звонок, Сервер может прислать:
Каждое из этих сообщений содержит атрибут
tag, идентифицирующий "ранний диалог" (одно из "звонящих" устройств абонента).
Когда начинается исходящий звонок, Клиент может прислать:
Исходящий звонок переходит в состояние "установлен", когда Сервер присылает сообщение
callConnected.
Исходящий звонок аварийно прекращается, если Сервер присылает сообщение
callDisconnected.
Клиент может прекратить исходящий звонок, используя операцию
callKill.
Входящие звонки начинаются с посылкой Клиенту Сервером сообщения
callIncoming. Сервер создаёт уникальный идентификатор для использования его в качестве значения атрибута
callLeg для сообщения
callIncoming. Во всех остальных сообщениях и запросах, имеющих отношение к этому звонку, будет использоваться то же значение атрибута
callLeg. Созданное Сервером для входящих звонков значение атрибута
callLeg использует префикс
inp, поэтому Клиент не должен использовать такой префикс для значений атрибута
callLeg в исходящих звонках.
Когда принимается входящий звонок, Сервер может прислать:
Когда принимается входящий звонок, Клиент может послать:
Входящий звонок аварийно прекращается (отменяется), если Сервер присылает сообщение
callDisconnected.
Клиент может прекратить обработку входящего звонка, отвергнув его с помощью запроса
callReject или перенаправив его с помощью запроса
callRedirect.
Клиент может принять входящий звонок с помощью запроса
callAccept, тем самым переведя его в состояние "установлен".
Когда исходящий вызов соединяется или когда входящий вызов принимается, звонок переходит в состояние "установлен". В установленном звонке медиа данные могут передаваться в обоих направлениях (если только одна из сторон не поставит звонок "на удержание").
Когда звонок установлен, Сервер может прислать:
Когда звонок установлен, Клиент может прислать:
Установленный звонок прекращается, если Сервер присылает сообщение
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 на [email protected] и [email protected].
Управление Медиаданными
Клиент должен освободить все медиа-объекты, связанные с этим звонком.
- 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
- идентификатор звонка.
- callId
- строка с Call-ID звонка.
- 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 звонка; при переводе звонка это параметр обычно меняется.
Тело:- Пустое.
- callInfo
- Эти асинхронные сообщения присылаются при получении запросов INFO:
- Атрибуты:
- callLeg
- идентификатор звонка.
Тело:- аналогично операции callSendInfo.
- makeCallReport
- Эти асинхронные сообщения данных присылаются при использовании операции makeCall.
- Тело:
- Строка, содержащая текущей статус операции. Сообщение содержит пустое тело при завершении операции.
Пример Входящий-01. Сессия входящего звонка с начальным SDP. Клиент не шлёт вызывающей стороне никаких "тонов дозвона".
Клиент получает сообщение
callIncoming с созданным Сервером атрибутом
callLeg.
S:
<callIncoming id="A001" callLeg="inp01" peer="[email protected]" >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="[email protected]" /> Клиент начинает подзывать пользователя (Клиент начинает "звонить").
Клиент информирует вызывающую сторону, что вызываемый абонент проинформирован о входящем звонке:
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="[email protected]" >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="[email protected]" >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="[email protected]" >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="[email protected]">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="[email protected]">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="[email protected]">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="[email protected]">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="[email protected]"/> 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="[email protected]"/> 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.
Некоторые клиенты могут не поддерживать выполнение всех операций через протокол 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
Руководство CommuniGate® Pro. Copyright © 1998-2019, Stalker Software, Inc.
