Содержание

 Содержание | Далее

Введение

Oktell в других проектах. COM-интерфейс

Принципы работы, архитектура

Регистрация библиотеки

Форматы и договоренности

Загрузка и выгрузка модуля

Служебные сообщения

Исключительные ситуации

Сервисное оповещение

Работа с номерным планом

Работа со статусом пользователя

Работа с правилами переадресации

Статистика коммутаций

Работа с логикой АТС

Автодозвон, осуществление вызовов

Работа с факсами

События АТС по каналу пользователя

Очередь ожидания

Контент оппозитного канала

Контент цепочки коммутаций

Конференц-связь

Работа с HAL

Обмен пользовательскими сообщениями

Вспомогательные методы

Осуществление и прием вызовов

Встраиваемые plugin-модули

Принципы работы, архитектура

Структура интерфейса

Формат параметров и выходных значений

Описание базовых элементов интерфейса

Общие модульные методы

Режим диалога

Общие методы двух режимов

Сервисное взаимодействие

Сервисное взаимодействие

Событие «OnQuery»

Метод «DoQuery»

Рекомендации разработчику

Объектная модель XML-парсера

Звонок с терминала

Цели и задачи

Варианты реализации

Подключение к COM-объекту

Регистрация библиотеки

Интерфейс взаимодействия

Использование native win32 библиотеки

Интерфейс взаимодействия

Использование .NET сборки

Интерфейс взаимодействия

Дополнительно

Локальные устройства. Телефон

Возможные проблемы и способы их устранения

Структура пространственной БД

Порты, используемые системой

Параметры файлов конфигурации

Форматы звуковых файлов

Порядок обновления программы в ручном режиме


Oktell в других проектах

 Содержание | Назад | Далее

В этом разделе:

— Принципы работы, архитектура

— Регистрация библиотеки

— Форматы и договоренности

— Загрузка и выгрузка модуля

— Служебные сообщения

— Исключительные ситуации

— Сервисное оповещение

— Работа с номерным планом

— Работа со статусом пользователя

— Работа с правилами переадресации

— Статистика коммутаций

— Работа с логикой АТС

Автодозвон, осуществление вызовов

Работа с факсами

События АТС по каналу пользователя

Очередь ожидания

Контент оппозитного канала

Контент цепочки коммутаций

Конференц-связь

— Работа с HAL

— Обмен пользовательскими сообщениями

— Вспомогательные методы

— Осуществление и прием вызовов


Регистрация библиотеки

Регистрация библиотеки

COM объект имеет .NET основу, поэтому его регистрация осуществляется с помощью специальной утилиты в составе Microsoft.NET. Стандартные способы регистрации могут не привести к желаемому результату.

После установки FRAMEWORK в его каталоге ( %SystemRoot%\Microsoft.NET\Framework\v1.1.4322\ ) появится файл regsvcs.exe. Вообще Framework вносит свой каталог в пути по умолчанию, поэтому из командной строки файл должен быть доступен из любого текущего каталога.

Классика жанра предполагает предварительное размещение сборок приложения в Global Assembly Cache, но поскольку из-за самостоятельной системы обновлений возникают сложности с заменой, а также со строгими именами сборок и динамическим связыванием, весь проект приложения Oktell размещается в отдельном каталоге безотносительно версий сборок. Именно в нем и следует регистрировать библиотеку.

Команда для исполнения регистрации выглядит:

regsvcs Oktell.ClientComLib.dll

либо

путь\regsvcs путь\Oktell.ClientComLib.dll

Команда для удаления регистрации:

regsvcs /u Oktell.ClientComLib.dll

В момент регистрации в командном окне выводятся результаты. Модуль regsvcs предоставляет еще несколько сервисов, подробнее о которых можно узнать, выполнив команду regsvcs /?.

После успешной регистрации (о чем будет сообщено дополнительно в командном окне) в каталоге с регистрируемой библиотекой появляется файл Oktell.ClientComLib.tlb.

Информация об объекте

Полное имя объекта: oktellClient.ComLib.OktellComClient

GUID объекта: 645CB11F-244B-4CD7-B0B8-D37D81A2D582

Интерфейс для вызова методов: interface IOktellComClient

GUID интерфейса: CDF085C-3476-4F10-88D3-D15323EAF654

Интерфейс для прямой регистрации callback-методов: interface IOktellComClientEvents

GUID интерфейса: CDF085C-3476-4F10-88D3-D15323EAF653

Интерфейс для событий (IConnectionPointContainer): dispinterface IOktellComEvents

GUID интерфейса: CDF085C-3476-4F10-88D3-D15323EAF655

Подписка на события объекта может быть осуществлена через IConnectionPointContainer (dispinterface IOktellComEvents), либо прямой регистрацией для отдельных событий адресов callback-методов (делегатов) (interface IOktellComClientEvents).

При реализации долгосрочных проектов необходимо иметь в виду, что обновления Oktell зачастую сопровождаются изменениями интерфейса основного COM-объекта. Как правило происходит лишь дополнение интерфейса ранее отсутствовавшими методами. Каждый из методов интерфейса IOktellComClient имеет установленный DispId для последующей идентификации и корректного вызова при замене библиотеки Oktell.ClientComLib.dll на более новую версию.

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

Независимый от версий интерфейс

В библиотеке описан альтернативный COM-объект, имеющий вместо интерфейса IOktellComClient интерфейс с единственным методом ExecMethod. С помощью этого метода можно вызвать любой из методов интерфейса IOktellComClient, описанных далее в настоящем разделе.

Полное имя объекта: oktellClient.ComLib.OktellComClientDynamic

GUID объекта: B6BC5DE5-8C98-4C16-A592-32A6B83F2F03

Интерфейс для вызова методов: interface IOktellComClient

GUID интерфейса: CDF085C-3476-4F10-88D3-D15323EAF654

Интерфейс для прямой регистрации callback-методов: interface IOktellComClientEvents

GUID интерфейса: CDF085C-3476-4F10-88D3-D15323EAF653

Интерфейс для событий (IConnectionPointContainer): dispinterface IOktellComEvents

GUID интерфейса: CDF085C-3476-4F10-88D3-D15323EAF655

Метод динамического вызова функций ядра описан

string ExecMethod ( string methodname, string param1, string param2 )

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

В остальном объект идентичен oktellClient.ComLib.OktellComClient, и далее в разделе рассматриваться не будет.

Для .NET разработчиков

COM объект, описываемый в руководстве, является ничем иным как оберткой для .NET экспортируемого типа oktellClient.ComLib.InnerComMapper, объявленного и реализованного в сборке oktell.ClientBaseLib.

Для упрощения интеграционной разработки и исключения COM-вызовов существует возможность осуществлять взаимодействие непосредственно через .NET объект. Его интерфейсы почти полностью аналогичны описанному интерфейсу COM-объекта в руководстве. Небольшая разница пристутсвует в способе отправки событий (callback-методов): некоторые вызовы становятся асинхронными именно в COM-обертке.


Форматы и договоренности

Форматы и общее

 Содержание | Назад | Далее

Конфигурация и формат параметров

Загрузка осуществляется на основе конфигурационного файла, лежащего где-либо рядом: с исполняемым модулем, запустившим процесс, со сборкой COM-объекта. Имя файла ищется под одним из имен: oktell.ClientComLib.dll.config, oktell.ClientStarter.exe.config, App.config. Параметры конфигурационного настроечного файла описаны в мануале к октеллу (здесь). Он дополнен только тремя параметрами - базового каталога для хранения логжурналов (WORK_ROOTDIR) и базового каталога для поиска сборок (MODULE_ROOTDIR) Если параметры не присутствуют, то модули ищутся в каталоге со сборкой COM, все временные папки, обновления и логи хранятся в каталоге исполняемого модуля или в каталоге со сборками (по умолчанию). Также возможно выставить параметр WORK_ROOTDIR_TYPE, который в отсутствие WORK_ROOTDIR будет указывать путь размещения всех временных папок (0 - каталог исполняемого модуля, 1 - каталог размещения сборок).

Взаимодействие осуществляется методами и callback-методами с передачей параметров простых типов (BOOL, INT, STRING). В случае необходимости передачи большого числа параметров или сложных параметров используется строковый параметр, содержащий внутри себя XML-структуру. Строка XML установленного образца по умолчанию в кодировке UTF-16 (может быть установлен любой формат методом SetXmlEncoding). Заголовки жестко фиксированы, содержимое согласно установленной структуре тэгов и их зависимостей, но произвольно по уровням вложенности и комбинациям.

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="" count="">

  <property_set name="" id="">

    <property_simple key="" value="" name="" />

    .....

    <property_simple key="" value="" name="" />

    <property_cdata key="" value=""><![CDATA[]]></property_cdata>

    .....

    <property_cdata key="" value=""><![CDATA[]]></property_cdata>

    <property_collection name="" count="">

      <property_set name="" id="">

         .....

      </property_set>

      .....

      <property_set name="" id="">

         .....

      </property_set>

    </property_collection>

  </property_set>

  .....

  <property_set name="" id="">

     .....

  </property_set>

</data>

</oktellcommapper>

Четыре основных тега внутренней структуры:

property_simple ( <property_simple key="" value="" name="" /> ) - элементарные свойства {key,value,name}, value и name могут отсутствовать.

property_cdata ( <property_cdata key="" value=""><![CDATA[]]></property_cdata> ) - полнотекстовые свойства с неизвестным заранее содержимым {key,value,text}, value может отсутствовать.

property_set ( <property_set name="" id="">...</property_set> ) - набор произвольного числа property_simple и property_cdata с допустимым присутствием одного тега property_collection.

property_collection ( <property_collection name="" count="">...</property_collection> ) - коллекция произвольного числа property_set.

Базовый внешний тег <data> представляет собой аналог <property_collection>.

Очевидна объектная модель, лежащая в основе подобным образом организованной структуры. Рекомендация: не делать различий между property_simple и property_cdata при парсинге XML в объекты.


Загрузка и выгрузка модуля

Служебные методы

Объект прослойки создается при первом запуске. До или после старта и вообще в ходе работы модуля есть возможность использовать сервисные функции установки параметров работы. Этот список будет пополняться. В данный момент среди служебных функций:

void SetAsyncEventing ( bool newvalue ). Устанавливает режим событийного оповещения - асинхронный режим/синхронный режим. По умолчанию FALSE - синхронный режим. Все методы, которые в любом случае должны быть асинхронными, платформа делает асинхронными независимо от установки режима.

void SetXmlLogging ( bool newvalue ). Устанавливает/выключает режим полного логирования всех передаваемых и получаемых параметров в виде XML в текущий CommonLog. По умолчанию пока TRUE. Используется для отладки. При передаче параметра он сначала логируется (c заголовком XML IN), а потом парсится. Выходные значения сначала формируются, а на выходе логируются (с заголовком XML OUT).

void SetAutoRetryLoad ( bool newvalue ). Устанавливает/снимает режим автопереподключения в случае неудач связанных с коннектом (после прохождения проверок, загрузок, конфигурации и других не связанных с откликами сервера этапов). Может быть снято/поставлено в любое время. Приложение при этом остается подключенным. Однако в случае временных подписок (например изменения состояний объектов номерного плана) после загрузки они не восстанавливаются. Помогает в случаях недолговременных сбоев в сети, при запросах сервера на перезапуск приложения. Но в случаях неверной конфигурации, пароля подключения, обновления - приложение должно самостоятельно останавливать модуль (либо специальным методом выгрузки, либо снятием флага - разница только на этапе корректной работы в подключенном состоянии).

void SetXmlEncoding ( int newvalue ). Устанавливает текущую кодировку для формирования и парсинга XML. По умолчанию используется Unicode (UTF-16). Параметр int определяет индекс требуемой кодировки в списке возможных вариантов:

Default = 0
ASCII = 1
BigEndianUnicode = 2
UTF7 = 3
UTF8 = 4
UTF16 = 5

void SetConfigPath ( string path ). Устанавливает явно путь к конфигурационному файлу ядра, который будет использован в случае его обнаружения. В противном случае поиск будет осуществляться в каталоге запускающего приложения и в каталоге, где зарегистрирован COM-объект. Имена файлов при поиске по умолчанию: oktell.clientstarter.exe.config, oktell.clientbaselib.dll.config, app.config, [имя стартового файла].config. Явное указание файла может потребоваться для реализации массового запуска приложений в терминальном режиме. Каждый из конфигурационных файлов устанавливает терминальный ключ, который должен отличаться у всех экземпляров, а также рабочую папку, в которой ядро будет осуществлять логирование, размещение временных файлов. Каждый из запускаемых экземпляров должен иметь уникальную рабочую папку. Сложности в случае терминального режима могут возникнуть только с обновлением комплекса. Каждый из запускаемых экземпляров будет в случае необходимости пытаться обновить ядро. Необходимо гарантировать запуск только одной копии при обновлении.

Все методы COM-класса ThreadSafe.

Методы запуска и остановки платформы

void ModuleStartAsync ( string login, string pass ). Метод старта асинхронной загрузки. Может быть вызван любое число раз. Внутри встроена проверка "один запуск - одна остановка". В некоторых случаях остановка производится автоматическая, тем самым устраняя необходимость дополнительно останавливать модуль, однако исключений лишние вызовы не повлекут. В момент асинхронного запуска приложение может ловить состояния по каналу события OnServiceMessage (описано здесь). В ходе подключения производится загрузка сборок, динамическое создание объекта платформы, поиск конфигурационных файлов и конфигурирование, проверка единичности запуска, осуществление и ожидание подключения к серверу по каналу TCP, логин, загрузка при необходимости модуля HAL поддержки локального устройства, создание других внутренних объектов, используемых в работе. Возникающие в ходе загрузки критические сбои передаются по каналу события OnError (описано здесь). При сбоях связанных с подключением к серверу, загрузчик находится в ожидании и циклических попытках снова подключиться. Прервать ожидание можно в любой момент вызовом метода выгрузки модуля. В случае неуспешного логина производится выход и выгрузка, если не стоит флаг AutoRetryLoad, который зациклит этап подключения до принудительного снятия флага либо командой выгрузки модуля.

Возможен запуск нескольких экземпляров приложений в терминальном режиме. Подробнее об этом в описании метода SetConfigPath().

void ModuleStop ( ). Метод синхронной остановки и выгрузки модуля. В ходе работы по каналам событий OnServiceMessage и OnError происходит информирование приложения о ходе и этапах выгрузки (описание здесь).

void ModuleStopAsync ( ). Метод асинхронной остановки и выгрузки модуля. В ходе работы по каналам событий OnServiceMessage и OnError происходит информирование приложения о ходе и этапах выгрузки (описание здесь).

Загрузив серверное приложение октелла в лог-журнале Service можно увидеть как сервер реагирует на логины, логоффы и управление каналом.

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

ВНИМАНИЕ! Во избежание блокировки (дедлока) запрещено вызывать метод ModuleStop в событийном потоке в ответ на поступающие события в ходе загрузки модуля, если заранее не выставлен режим асинхронного событийного взаимодействия.


Служебные сообщения

Служебные сообщения и этапы подключения

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

Список кодов:

11001 //Aborted. Загрузка прервана.

Этапы загрузки

11011 //CheckingAssemblies. Этап проверки, поиска и загрузки сборок.

11012 //CreatingMapperObject. Этап создания внутреннего объекта, нижестоящего под ком-оберткой.

11013 //Configuring. Этап конфигурации из файла. Поиск, обнаружение.

11014 //CheckingMutex. Этап проверки одной копии.

11015 //NotStartedYetCannotStop. Код случая, если вызывается стоп для нестартованного объекта.

11101 //Initialization. Инициализация загрузчика.

11102 //WaitForConnection. Ожидание подключения к серверу.

11103 //WaitForLogin. Ожидание обработки логина.

11104 //LiveUpdate. Закачаны обновления и запрошен перезапуск с замещением сборок.

11105 //ConnectionError. Ошибка подключения. Возможен вариант прерывания загрузки методом ModuleStop на этапе ожидания. подключения.

11106 //LoadException.

Постлогин этапы

11201 //LoginSuccess. Успешный логин.

11202 //LoadingHAL. Загрузка аппаратного модуля.

11203 //HALError. Ошибка загрузки аппаратного модуля.

11204 //AfterLoad. После загрузки выставление служебных полей.

11205 //LoadSuccess. Загрузка завершена.

11206 //Ready. Модуль иницилизирован и готов к обработке вызовов.

Этапы выгрузки

11301 //StopConnection. Подготовка к остановке.

11302 //Dispose. Выгрузка служебных объектов.

11303 //StopHAL. Остановка аппаратного модуля.

11304 //Stopped. Выгрузка завершена.

Ответы сервера на логине

11501 //Unknown

11502 //Exception

11503 //IncorrectLoginPass. Неверная комбинация Логин-пароль.

11504 //WorkpaceUndefined. Рабочее место не инициализировано (служебный код).

11505 //WorkpaceNotFound. Рабочее место не определено в карте офиса или не сопоставлено по адресам. В этом случае в логе появляется перечень адресов компьютера, переданных серверу на сопоставление рабочего места.

11506 //UserAlreadyRegistered. Пользователь уже зарегистрирован в системе и новый вход запрещен.

11507 //IncorrectServer. Клиент коннектится не к своему серверу. В смысле в карте существует несколько серверов, клиент цепляется не к тому, с которым соединен в карте.

11508 //CannotLogin. Подключение невозможно (разрыв связи на логине, изменение обстановки).

11509 //SystemAdminDenied. Вход системному администратору заблокирован в связи с работоспособностью сервера и наличием учетных записей администраторов.

11510 //ServerInitializing. Отказ сервера по причине загрузки его самого. Вход еще не разрешен (идет загрузка) или уже не разрешен (после команды на остановку и перезапуск).

11511 //PBXSSNotReady. Сервер состояний не готов или не запущен.

11512 //FreeVersionDenied. Запрет работы сервером по причине использования свободно распространяемого ключа защиты.

Этапы подключения к серверу. Возникают после 11102, но до следующих этапов

12101 //Started. Запуск подключения.

12102 //Restarted. Перезапуск подключения.

12103 //SearchingUpdates. Подключение установлено. Поиск обновлений.

12104 //DownloadingUpdates. Загрузка обновлений.

12105 //UpdatesDownloadFinish. Загрузка обновлений завершена.

12106 //FullRestartToMoveUpdates. Ожидание перед возвратом и командой на перезапуск.

12107 //RegisterCP. Регистрация на сервере, настройка прокси, тестовый обмен объектами.

12108 //SuccessConnection. Успешное подключение.

12109 //ConnectionError1. Ошибка сокета на первой итерации.

12110 //ConnectionError2. Ошибка сокета на последующих итерациях.

12111 //ConnectionError3. Прочие ошибки подключения.

Сообщения в ходе работы

13101 //Shutdown. В ходе работы поступила команда сервера на выгрузку клиента (возможно администратор запросил).

13102 //Restart. В ходе работы поступила команда сервера на перезапуск клиента (либо перезагрузка сервера, либо админ запросил).

13103 //ConnectionLost. В ходе работы потеряна связь с сервером. Пинг не прошел несколько раз подряд, или не поступил ответный пинг сервера по обратному каналу.

При установленном флаге автоперезапуска (метод SetAutoRetryLoad) в случае возникновения сбоев система будет вновь запускать процесс логина. Это помогает в случаях 11511, 11510, 13101, 13102, 13103, если сбой носил временный характер. В любой момент отключением флага автоперезапуска или остановкой модуля можно прервать цикличность.

Список кодов может на этапе работы над модулем дополняться и возможно видоизменяться. Какие-то вещи можно зафильтровать, какие то расширить. Это касается и будущих блоков.

Вызов всех методов, работающих с объектами сервера, возможен только после получения события 11206 (Ready), так как только непосредственно перед его генерацией выставляется флаг успешной загрузки, допускающий сервисные вызовы.


Исключительные ситуации

Исключительные ситуации

Система в случае сбоев генерит исключения по каналу события OnError. Ошибки и исключительные ситуации передаются вместе с контекстным описанием (int code, string message).

10001 //GlobalInnerException. Исключение заранее неизвестной природы. Текст исключения.

10002 //MutexBusy. Обнаружении копии приложения в текущей терминальной сессии.

10003 //ConfigurationNotFound. Конфигурационный файл не обнаружен или кривой. Конкретное описание и текст ошибки

10011 //ObjectNotInitialized. Объект, предоставляющего сервис платформы не существует. Текст ошибки. Внутренняя ошибка. Наружу передается для быстрого реагирования.

10012 //ObjectEventHandleException. Ошибка подписки на события. имя события, текст ошибки.

10013 //ObjectEventHandleCriticalException. Критическая ошибка подписки на события. Скорее всего несоответствие типов. имя события, текст ошибки

10020 //GenerageExternalEvent. исключение при пробросе события наружу. События любой природы. OnCommunicate или OnServiceMessage.

10021 //PassingParameterException. Передаваемый XML параметр NULL или неверного формата. Вызвал исключение при попытке обработать

10022 //PassingParameterIncorrect. Передаваемый XML параметр не содержит ожидаемого контекста.

10101 //AssemblyNotFount. Сборка не обнаружена. Текст описательный.

10102 //AssemblyLoadException. Ошибка при загрузке сборки. Текст ошибки.

10103 //SubAssemblyLoadException. Ошибка при загрузке зависимой сборки. Текст ошибки.

10104 //TypeNotFound. Необходимый тип не обнаружен в сборке. Текст описания.

10105 //TypeCreateError. Ошибка при создании типа. Текст ошибки.

10106 //TypeLoadException. Ошибка загрузки и инициализации. Текст ошибки

10107 //MethodNotFound. Метод не найден. Имя метода, текст ошибки.

10108 //ExecutionException. Исключение при вызове метода. Текст исключения.

Список кодов может на этапе работы над модулем дополняться и возможно видоизменяться. Какие-то вещи можно зафильтровать, какие то расширить. Это касается и будущих блоков.


Сервисное оповещение

Канал сервисного оповещения

Сервисные события системы поступают по каналу события OnCommunicate. Параметризованные строкой с XML содержимым в UTF-16. Формат поступающих xml обсуждаем. Общие принципы формирования структуря xml параметров представлены здесь, примеры конкретных реализация представлены в текущем разделе. При использовании режима XmlLogging (метод SetXmlLogging), все генерируемые xml-параметры на выходе размещаются в CommonLog с заголовком xmlevent.

Типы событий:

ShutdownRequested = 101
RestartRequested = 102
ConnectionLost = 103
UserStateChanged = 111
Notify = 112
VoiceMail = 113
UserMessage = 114
PersonalStateChanged = 115

HALSrvRegSuccess = 201
HALSrvRegTimeout = 202
HALDeviceFound = 203
HALDeviceLost = 204
HALLightenKey = 211
HALHeadsetParams = 212
HALClearNFieldNow = 213
HALClearNFieldNext = 214

CommutationStarted = 231
CommutationStopped = 232
FaxStarted = 233
FaxStopped = 234
FaxFilesReceived = 235
RingStarted = 236
RingFinished = 237
ACMStarted = 238
ACMFinished = 239
FlashHoldAction = 240
ChainStateChange = 241
LineStateChange = 242

ConferenceListChanged                        = 261

ConferenceCompositionChanged                = 262

ConferenceCompetitorStateChanged        = 263

ConferenceEntranceRequest                = 264

ConferenceEntranceDenied                = 265

ConferenceEntrancePermitted                = 266

ConferenceNotifyInvite                        = 267

ConferenceUserStateChanged                = 268

Описание и примеры событий 101 - 114 приведены ниже в текущем разделе, а остальных - в соответствующих им разделах.

ShutdownRequested (101). Возникает при запросе администратором oktell выгрузки клиентских (или клиентского) приложения. Дублируется в канале события OnServiceMessage канале (13101 - Shutdown).

Пример:

?<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="101" name="shutdownrequested" />

</data>

</oktellcommapper>

RestartRequested (102). Возникает в случае падения TCP канала связи с сервером. Дублируется в канале события OnServiceMessage канале (13102 - Restart).

Пример:

?<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="102" name="restartrequested" />

</data>

</oktellcommapper>

ConnectionLost (103). Возникает в случае падения TCP канала связи с сервером. Дублируется в канале события OnServiceMessage канале (13103 - ConnectionLost).

Пример:

?<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="103" name="connectionlost" />

</data>

</oktellcommapper>

UserStateChanged (111). Возникает при смене состояния текущего зарегистрированного пользователя на сервере. Изменяется только сервером. Также вместе с состоянием приходит флаг-признак переадресации. Для изменения состояния по инициативе клиентского приложения существует метод SetUserState ( string xml ), который посылает запрос серверу на проведения смены состояний. Сервер может отказать по своему усмотрению.

Возможные состояния:

usDisconnected = 0. Пользователь отключен. Для текущего пользователя - отсутствие связи с сервером логики.
usReady = 1. Пользователь на месте в готовом состоянии, не занят в задачах, линия свободна.
usLunch = 2. Оператор в перерыве.
usOff = 3. Пользователя нет на месте. Выставляется, если пользователь не снял трубку в ходе поступающего вызова в течение установленного времени. Фильтрует дальнейшее поступление звонков
usFullbusy = 5. Пользователь занят в задаче или в разговоре
usReserved = 6. Пользователь зарезервирован задачей (быстрое состояние)
usWOphone = 7. Пользователь зарегистрирован, но линия отсутствует, отключена или в неопределенном состоянии.

Состояния пользователей также используются в других событиях и методах (например событие PersonalStateChanged (115) или метод SetUserState )

Пример:

?<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="111" name="userstatechanged">

    <property_simple key="newstate" value="7" name="usWOphone" />

    <property_simple key="redirect" value="0" />

  </event>

</data>

</oktellcommapper>

Notify (112). Возникает при поступлении системного уведомления, которые генерирует сервер или нижняя прослойка клиентского приложения. Существуют различные типы(направления). По аналогии с клиентским приложением oktell уведомления содержат признаки: автоскрытие, цвет, тип, время поступления, признак сохранения в БД (в случае TRUE можно в разделе истории уведомлений увидеть), отправитель, текст. Каждый тип уведомления имеет свой установленный цвет отображения и иконку (это делается для привыкания к аналоговой информации и последующего быстрого подсознательного реагирования). Свойство "цвет" используется только типом nltColor поступающих уведомлений.

Типы уведомлений - флаговые, но ходят по одному.

nltNone = 0x00000,
nltControlEvent = 0x00002, Контрольное событие
nltPBXinfo = 0x00008, Служебная информация АТС
nltInformation = 0x00010, Общая информация
nltIncomingCall = 0x00020, Входящий вызов
nltTimer = 0x00080, ??
nltCallbackOrder = 0x00100, Заказ на встречный звонок
nltApplication = 0x00200, Сообщение клиентского приложения
nltApplicationWarn = 0x00400, Предупреждение клиентского приложения
nltApplicationInfo = 0x00800, Общая информация клиентского приложения
nltApplicationErr = 0x01000, Ошибка клиентского приложения
nltColor = 0x40000, Окошко изменяемого цвета из сценариев

Пример:

?<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="112" name="notify">

    <property_simple key="guid" value="00000000-0000-0000-0000-000000000000" />

    <property_simple key="autohide" value="1" />

    <property_simple key="backcolor_argb" value="0" />

    <property_simple key="type" value="8" name="nltPBXinfo" />

    <property_simple key="datetime" value="12.07.2008 18:35:06" />

    <property_simple key="dbsaved" value="1" />

    <property_cdata key="sender"><![CDATA[Системная АТС]]></property_cdata>

    <property_cdata key="text"><![CDATA[Зарегистрирована линия 16016]]></property_cdata>

  </event>

</data>

</oktellcommapper>

VoiceMail (113). Возникает при поступлении нового голосового сообщения. Тело сообщения отсутствует, служит для отображения статусной пиктограмки, запрос на получение почты производится в соответствующем модуле.

Пример:

?<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="113" name="voicemail" />

</data>

</oktellcommapper>

UserMessage (114). Поступление сообщения от другого пользователя системы через внутренний мессенджер.

Пример:

?<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="112" name="usermessage">

    <property_simple key="guid" value="37ccb224-ff71-3836-c410-a73782ef8d19" />

    <property_simple key="datetime" value="12.07.2008 20:29:11" />

    <property_simple key="senderid" value="d03a522f-b399-aa37-cb2a-943cf24d113e" />

    <property_cdata key="sendername"><![CDATA[Бочкарев Евгений]]></property_cdata>

    <property_cdata key="text"><![CDATA[Зайди плиз как освободишься..]]></property_cdata>

  </event>

</data>

</oktellcommapper>


Работа с номерным планом

Методы для работы с отображением номерного плана

Набор методов и событий для реализации модуля отображения объектов номерного плана и их состояний. Методы осуществления вызовов в разделе логики АТС (здесь).

string GetPersonalStates ( ). Возвращает состояния объектов номерного плана. Объемный XML установленного образца. Формат обсуждаем. Перечень всех номеров с кодами GUID, префиксами набора, признаком типа номера, в случае если номер индивидуальный стандартный - состояние объекта. Также для каждого стандартного номера перечислены все объекты, входящие в структуру номера. По каждому объекту - код, тип (user, fxsline, usbline, sipline) и ссылкой на отдел, на который назначен. В случае если объект входит в несколько номеров, информация по нему дублирутся в каждом номере.

Формат возвращаемого xml (на примере):

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="personal" count="2">

  <property_set name="number" id="ea156be4-b496-4ddc-9217-fa708cb3a904">

    <property_simple key="guid" value="ea156be4-b496-4ddc-9217-fa708cb3a904" />

    <property_simple key="prefix" value="12" />

    <property_cdata key="caption"><![CDATA[Сметчики]]></property_cdata>

    <property_simple key="isgroup" value="1" />

    <property_simple key="grouptype" value="0" name="standard" />

    <property_collection name="elements" count="2">

      <property_set name="reactobject" id="cf8330f4-a0bf-4779-9539-ab8ea6c49df7">

        <property_simple key="guid" value="cf8330f4-a0bf-4779-9539-ab8ea6c49df7" />

        <property_cdata key="department" value="37ccb224-ff71-3836-c410-a73782ef8d19"><![CDATA[Сметный отдел]]></property_cdata>

        <property_simple key="type" value="0" name="user" />

      </property_set>

      <property_set name="reactobject" id="3145962b-2141-4b63-960e-9fb7142e0c7b">

        <property_simple key="guid" value="3145962b-2141-4b63-960e-9fb7142e0c7b" />

        <property_cdata key="department" value="00000000-0000-0000-0000-000000000000"><![CDATA[Прочие подразделения]]></property_cdata>

        <property_simple key="type" value="1" name="fxsline" />

      </property_set>

    </property_collection>

  </property_set>

  <property_set name="number" id="a4bb8d39-082a-4fde-957b-ff14ddd66f4e">

    <property_simple key="guid" value="a4bb8d39-082a-4fde-957b-ff14ddd66f4e" />

    <property_simple key="prefix" value="03" />

    <property_cdata key="caption"><![CDATA[Портал знакомств - Главное меню]]></property_cdata>

    <property_simple key="isgroup" value="1" />

    <property_simple key="grouptype" value="2" name="ivr" />

  </property_set>

</data>

</oktellcommapper>

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

standard = 0,        //Стандартный групповой.
fast = 1,        //Быстрый набор.
ivr = 2        //Запуск сценария IVR.

Типы элементов, участвующих в формировании стандартных номеров (поле type ветки reactobject):

user = 0,        //Пользователь
fxsline = 1,        //Внутреннаяя аналоговая линия
usbline = 2,        //USB линия
sipline = 3        //Внутренний SIP-канал

void SetListenPersonalChanges ( bool newvalue ). Осуществляет подписку/отписку от режима прослушивания серверных сообщений о факте смены состояния одним из объектов номерного плана. Рекомендуется в целях экономии ресурсов и трафика подключаться только при работе с интерфейсом номерного плана, и отписываться при закрытии интерфейса. На старте работы с интерфейсом - загружать весь перечень и выстраивать по нему, после чего отслеживать изменения. События поступают через канал сервисного оповещения OnCommunicate

PersonalStateChanged (115). Событие смены состояния объектом номерного плана. Возникает только в случае подписки на события этого типа методом SetListenPersonalChanges.

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="115" name="personalstatechanged">

    <property_simple key="guid" value="916351c3-be6a-4a29-877a-6c8c4b54f8af" />

    <property_simple key="newstate" value="1" name="usReady" />

  </event>

</data>

</oktellcommapper>


Работа со статусом пользователя

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

string GetCurrentUserFullInfo ( ). Возвращает xml-структуру с описанием текущего авторизованного пользователя, включающую расширенное ролевое описание права доступа к модулям. При расширении прав впоследствии формат значения может видоизменяться количественно и качественно.

Формат возвращаемого xml (на примере):

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="userinfo">

  <property_simple key="id" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8" />

  <property_simple key="type" value="1" name="utUser" />

  <property_cdata key="name"><![CDATA[Петр]]></property_cdata>

  <property_simple key="isoperator" value="1" />

  <property_simple key="group" value="c4e3b424-3048-4cce-a2e4-033c532a7d99" name="Программисты" />

  <property_cdata key="login"><![CDATA[Peter]]></property_cdata>

  <property_cdata key="password"><![CDATA[123]]></property_cdata>

  <property_cdata key="role" value="41fbf675-8f73-488e-83ca-c108b915f51d"><![CDATA[Администратор]]></property_cdata>

  <property_simple key="callerid" value="" />

  <property_cdata key="info"><![CDATA[]]></property_cdata>

  <property_collection name="properties" count="1">

    <property_set name="role" id="41fbf675-8f73-488e-83ca-c108b915f51d">

      <property_cdata key="extwp" value="1"><![CDATA[Расширенное рабочее место]]></property_cdata>

      <property_cdata key="candeleterecords" value="1"><![CDATA[Возможность удалять записи статистики]]></property_cdata>

      <property_cdata key="showspecialscripts" value="1"><![CDATA[Показывать cистемные сценарии]]></property_cdata>

      <property_cdata key="caneditreports" value="1"><![CDATA[Возможность редактировать индикаторы call-центра]]></property_cdata>

      <property_cdata key="caneditindicators" value="1"><![CDATA[Возможность редактировать отчеты статистики сall-центра]]></property_cdata>

      <property_cdata key="viewsvctasks" value="1"><![CDATA[Доступ к служебным задачам]]></property_cdata>

      <property_cdata key="canuseacm" value="1"><![CDATA[Доступ к сервису автодозвона]]></property_cdata>

      <property_cdata key="canusemessagingout" value="1"><![CDATA[Возможность отправки сообщений]]></property_cdata>

      <property_cdata key="canusefax" value="1"><![CDATA[Доступ к офис-факсу]]></property_cdata>

      <property_cdata key="showphoneindialogcards" value="1"><![CDATA[Отображать телефон в диалоговых формах]]></property_cdata>

      <property_cdata key="viewoffice" value="1"><![CDATA[Офис]]></property_cdata>

      <property_cdata key="viewofficepersonels" value="1"><![CDATA[Сотрудники]]></property_cdata>

      <property_cdata key="viewofficestatistics" value="1"><![CDATA[Статистика]]></property_cdata>

      <property_cdata key="viewofficemycalls" value="1"><![CDATA[Мои звонки]]></property_cdata>

      <property_cdata key="viewofficeclients" value="1"><![CDATA[Клиенты]]></property_cdata>

      <property_cdata key="viewofficecabinet" value="1"><![CDATA[Кабинет]]></property_cdata>

      <property_cdata key="viewofficeredirect" value="1"><![CDATA[Переадресация]]></property_cdata>

      <property_cdata key="viewcallcenter" value="1"><![CDATA[Call-центр]]></property_cdata>

      <property_cdata key="viewcallcenteroperators" value="1"><![CDATA[Операторы]]></property_cdata>

      <property_cdata key="viewcallcenterprojects" value="1"><![CDATA[Проекты]]></property_cdata>

      <property_cdata key="viewcallcenterlists" value="1"><![CDATA[Таблицы абонентов]]></property_cdata>

      <property_cdata key="viewcallcenterscripts" value="1"><![CDATA[Сценарии]]></property_cdata>

      <property_cdata key="viewcallcentertasks" value="1"><![CDATA[Задачи]]></property_cdata>

      <property_cdata key="viewcallcentercontrolevents" value="1"><![CDATA[Контрольные события]]></property_cdata>

      <property_cdata key="viewcallcenterresources" value="1"><![CDATA[Ресурсы]]></property_cdata>

      <property_cdata key="viewcallcenterindicators" value="1"><![CDATA[Индикаторы]]></property_cdata>

      <property_cdata key="viewcallcenterstat" value="1"><![CDATA[Статистика call-центра]]></property_cdata>

      <property_cdata key="viewcallcenterreports" value="1"><![CDATA[Отчеты]]></property_cdata>

      <property_cdata key="viewcallcenterworkplace" value="1"><![CDATA[Мое рабочее место]]></property_cdata>

      <property_cdata key="viewadmin" value="1"><![CDATA[Администрирование]]></property_cdata>

      <property_cdata key="viewadminusers" value="1"><![CDATA[Пользователи]]></property_cdata>

      <property_cdata key="viewadminofficemap" value="1"><![CDATA[Карта сети]]></property_cdata>

      <property_cdata key="viewadminlines" value="1"><![CDATA[Линии]]></property_cdata>

      <property_cdata key="viewadminrights" value="1"><![CDATA[Права]]></property_cdata>

      <property_cdata key="viewadmininnernumbers" value="1"><![CDATA[Внутренние номера]]></property_cdata>

      <property_cdata key="viewadminclientforms" value="1"><![CDATA[Управление клиентами]]></property_cdata>

      <property_cdata key="viewadminsettings" value="1"><![CDATA[Общие настройки]]></property_cdata>

      <property_cdata key="viewadminscripts" value="1"><![CDATA[Сценарии]]></property_cdata>

      <property_cdata key="viewadminmonitoring" value="1"><![CDATA[Мониторинг]]></property_cdata>

      <property_cdata key="viewadminmobilemasks" value="1"><![CDATA[Мобильные маски]]></property_cdata>

      <property_cdata key="viewadminmobilestatistics" value="1"><![CDATA[Мобильная статистика]]></property_cdata>

      <property_cdata key="viewofficeclientscustomfilter" value="1"><![CDATA[Произвольные фильтры]]></property_cdata>

      <property_cdata key="viewofficeclientsadd" value="1"><![CDATA[Добавление клиентов]]></property_cdata>

      <property_cdata key="viewofficeclientsdelete" value="1"><![CDATA[Удаление клиентов]]></property_cdata>

      <property_cdata key="viewofficeclientsedit" value="1"><![CDATA[Редактирование клиентов]]></property_cdata>

    </property_set>

  </property_collection>

</data>

</oktellcommapper>

string GetUserState ( ). Возвращает текущее состояние и статус переадресации текущего авторизованного пользователя.

Формат возвращаемого xml (на примере):

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="userstate">

  <property_set name="currentstateinfo">

    <property_simple key="state" value="1" name="usReady" />

    <property_simple key="redirect" value="0" />

  </property_set>

</data>

</oktellcommapper>

void SetUserState ( string xml ). Передает серверу команду на смену состояния и/или статуса переадресации текущего авторизованного пользователя. Не любое состояние может быть установлено. Смена состояния осуществляется сервером только в случае успешного контроля корректности.

Формат передаваемого параметра xml (на примере):

Пример 1

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="userstate">

  <property_set name="currentstateinfo">

    <property_simple key="state" value="2" />

<property_cdata key="description"><![CDATA[Ушел на обед]]></property_cdata>

    <property_simple key="redirect" value="0" />

  </property_set>

</data>

</oktellcommapper>

Пример 2

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="userstate">

  <property_set name="currentstateinfo">

    <property_simple key="state" value="1" />

    <property_simple key="redirect" value="1" />

  </property_set>

</data>

</oktellcommapper>

string GetLineState ( ). Возвращает текущее состояние линии пользователя. В случае ее отсутствия возвращает код состояния "отключена", в случае нескольких линий возвращает состояние первой из них.

Формат возвращаемого xml (на примере):

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="linestate">

  <property_set name="currentlinestateinfo">

    <property_simple key="state" value="4" name="lsReady" />

  </property_set>

</data>

</oktellcommapper>

Допустимые состояния пользователя

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

public enum EUserState

{

usDisconnected = 0,        //Не авторизован. Для всех, когда нет связи с сервером логики
usReady = 1,        //Готов, на месте. Для всех, когда готовность
usLunch = 2,        //Перерыв в call-центре. Для операторов, когда готовность
usOff = 3,        //Нет на месте. Для всех, когда не была снята трубка в момент вызова и установлен режим перевода пользователей в OFF в настройках системы.
usFullbusy = 5,        //Занят. Для всех, когда осуществляется работа в задаче или в разговоре
usReserved = 6,        //Зарезервирован. Для всех, когда свободный пользователь зарезервирован транзакцией для осуществления намеченных действий и не может быть разделен с другими транзакциями
usWOphone = 7        //Без телефона. Для всех, когда линия пользователя находится в одном из нерабочих состояний или отсутствует вовсе

}

Допустимые состояния линии

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

public enum ELineState

{

lsDisconnected = 0x00000001,        //Отсутствует/не подключена.
lsOff = 0x00000002,        //Выключена.
lsReady = 0x00000004,        //Готовность.
lsHookUp = 0x00000008,        //Снятая трубка.
lsIncomingCall = 0x00000010,        //Входящий вызов.
lsCommutated = 0x00000020,        //Коммутация.
lsWait = 0x00000040,        //Ожидание.
lsFlash = 0x00000080,        //Флеш.
lsWaitDown = 0x00000100,        //Ожидание обратного вызова.
lsListenBusy = 0x00000200,        //Сигнал отбоя.
lsUndefined = 0x00000400,        //Неопределенное состояние.
lsReserved = 0x00000800,        //Зарезервирована.
lsReservedByTask = 0x00001000        //Зарезервирована задачей.

}

Методы для определения присутствия в call-центре

Режим call-центра предоставляет доступ пользователей к работе с проектами. Это касается как визуальных интерфейсов, так и участия в обработке звонков по задачам. Режим колл-центра лицензируется, лицензии являются конкурентными. Одновременно в режиме может находиться не более установленного ключом числа пользователей (операторов и/или супервизоров). При попытке входа очередного пользователя и отсутствии свободных лицензий сервер во входе отказывает. При выходе пользователя, находящегося в call-центре, (остановке клиентского приложения) его присутствие в режиме остается. Таким образом при следующей загрузке он автоматически попадает в call-центр. Однако, если в момент отсутствия (неавторизованности) пользователя, находящегося по умолчанию в call-центре, будет осуществлен вход любого другого пользователя, запросившего лицензию, в условиях нехватки отсутствующий пользователь будет принудительно выведен из режима call-центра, и его лицензия будет использована.

bool CallCenter_IsInside ( ). Возвращает признак присутствия текущего авторизованного пользователя в режиме call-центра системы. TRUE - пользователь в call-центре, FALSE - вне.

bool CallCenter_Enter ( ). Осуществляет попытку входа в режим call-центра системы. В случае успеха возвращает TRUE, в случае отказа по отсутствию лицензий или сбоя возвращает FALSE.

void CallCenter_Exit ( ). Осуществляет выход текущего пользователя из режима call-центра.

bool CallCenter_SetBusyInExternalTask ( ). Осуществляет резервирование пользователя в виртуальной для Oktell внешней задаче CRM. Фактически блокирует анализатор очереди и перевод пользователя в состояние ГОТОВ после разрыва связи.

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

Вызов метода может производиться в любое время. Рекомендуется осуществлять резервирование в момент начала работы с внешним блоком (карточкой, формой), но после коммутации. Не запрещается также использовать режим резервирования и в отсутствие коммутации, однако следует иметь в виду, что пользователь не сможет воспользоваться телефонным аппаратом, так как для работы в АТС ему необходимо иметь возможность быть зарезервированным на работу в ней; резервирование же в задаче блокирует сервис АТС. Отмена режима виртуального резервирования производится с помощью вызова метода CallCenter_SetFreeInExternalTask, выходом из Call-центра или выгрузкой модуля. Возвращает TRUE, если резервирование произведено, и FALSE, если пользователь уже был в резервировании задачей (внешней или внутренней к Oktell).

bool CallCenter_SetFreeInExternalTask ( ). Осуществляет вывод пользователя из резервирования в виртуальной для Oktell внешней задаче CRM. Вместе с этим осуществляет анализ очереди и обратный дозвон на канал пользователя в случае, если в очереди кто-либо ожидает соединения. В противном случае переводит пользователя в состояние ГОТОВ и разрешает всем службам резервировать его под свои нужды. Возвращает TRUE, если резервирование отменено, и FALSE, если пользователь не был зарезервирован или был зарезервирован во внутреннюю задачу Oktell.

bool CallCenter_CheckBusyInExternalTask ( ). Проверяет, является ли текущий пользователь зарезервированным в виртуальную для Oktell внешнюю задачу CRM (метод CallCenter_SetBusyInExternalTask). Возвращает TRUE, если зарезервирован, FALSE, если не зарезервирован или задача не является внешней виртуальной CRM-задачей.


Работа с правилами переадресации

Методы для работы с правилами переадресации

string Redirect_GetUserRules ( ). Возвращает XML-строку с набором существующих для текущего авторизованного пользователя правил переадресации. В случае ошибки возвращается NULL.

Формат возвращаемого xml (на примере):

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="redirectrules" count="4">

  <property_set name="redirectrule" id="86c7eeb5-a805-493a-a557-6675b884885c">

    <property_simple key="id" value="86c7eeb5-a805-493a-a557-6675b884885c" />

    <property_cdata key="caption"><![CDATA[тест субботы]]></property_cdata>

    <property_cdata key="description"><![CDATA[]]></property_cdata>

    <property_simple key="priority" value="1" />

    <property_simple key="enabled" value="1" />

    <property_simple key="onlyforredirectstate" value="0" />

    <property_simple key="cascaderedirect" value="0" />

    <property_simple key="numberdestination" value="89050215951" />

    <property_simple key="userid" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8" />

    <property_simple key="currentstate" value="1" name="Enabled" />

    <property_collection name="extra" count="2">

      <property_set name="abonents" />

      <property_set name="time">

        <property_collection name="time" count="1">

          <property_set name="periodinfo">

            <property_simple key="format" value="HH:mm" />

            <property_simple key="weekday" value="6" name="Saturday" />

            <property_simple key="begin" value="10:00" />

            <property_simple key="end" value="13:00" />

          </property_set>

        </property_collection>

      </property_set>

    </property_collection>

  </property_set>

  <property_set name="redirectrule" id="6bbe38b3-094c-4424-b938-539d7e6382c5">

    <property_simple key="id" value="6bbe38b3-094c-4424-b938-539d7e6382c5" />

    <property_cdata key="caption"><![CDATA[Общая переадресация]]></property_cdata>

    <property_cdata key="description"><![CDATA[]]></property_cdata>

    <property_simple key="priority" value="2" />

    <property_simple key="enabled" value="1" />

    <property_simple key="onlyforredirectstate" value="0" />

    <property_simple key="cascaderedirect" value="0" />

    <property_simple key="numberdestination" value="31" />

    <property_simple key="userid" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8" />

    <property_simple key="currentstate" value="1" name="Enabled" />

    <property_collection name="extra" count="2">

      <property_set name="abonents">

  <property_collection name="abonents" count="2">

<property_set name="abonent">

<property_simple key="type" name="1" value="ExtNumber" />

<property_simple key="id" name="00000000-0000-0000-0000-000000000000" />

        <property_simple key="number" name="4952778419" />

<property_cdata key="description"><![CDATA[Теща]]></property_cdata>

                 </property_set>

<property_set name="abonent">

<property_simple key="type" name="1" value="User" />

            <property_simple key="id" name="837afb4a-2be1-5ad3-9bba-1422f2dae0c7" />

<property_simple key="number" name="" />

<property_cdata key="description"><![CDATA[Иван Петрович]]></property_cdata>

                 </property_set>

  </property_collection>

</property_set>

      <property_set name="time">

        <property_collection name="time" count="4">

          <property_set name="periodinfo">

            <property_simple key="format" value="HH:mm" />

            <property_simple key="weekday" value="3" name="Wednesday" />

            <property_simple key="begin" value="04:00" />

            <property_simple key="end" value="08:00" />

          </property_set>

          <property_set name="periodinfo">

            <property_simple key="format" value="HH:mm" />

            <property_simple key="weekday" value="4" name="Thursday" />

            <property_simple key="begin" value="04:00" />

            <property_simple key="end" value="08:00" />

          </property_set>

          <property_set name="periodinfo">

            <property_simple key="format" value="HH:mm" />

            <property_simple key="weekday" value="5" name="Friday" />

            <property_simple key="begin" value="09:00" />

            <property_simple key="end" value="16:00" />

          </property_set>

          <property_set name="periodinfo">

            <property_simple key="format" value="HH:mm" />

            <property_simple key="weekday" value="6" name="Saturday" />

            <property_simple key="begin" value="09:00" />

            <property_simple key="end" value="16:00" />

          </property_set>

        </property_collection>

      </property_set>

    </property_collection>

  </property_set>

  <property_set name="redirectrule" id="bcd09c4c-9b41-41e8-a62f-abfa01f3f668">

    <property_simple key="id" value="bcd09c4c-9b41-41e8-a62f-abfa01f3f668" />

    <property_cdata key="caption"><![CDATA[t3]]></property_cdata>

    <property_cdata key="description"><![CDATA[]]></property_cdata>

    <property_simple key="priority" value="3" />

    <property_simple key="enabled" value="1" />

    <property_simple key="onlyforredirectstate" value="0" />

    <property_simple key="cascaderedirect" value="0" />

    <property_simple key="numberdestination" value="" />

    <property_simple key="userid" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8" />

    <property_simple key="currentstate" value="1" name="Enabled" />

    <property_collection name="extra" count="2">

      <property_set name="abonents" />

      <property_set name="time">

        <property_collection name="time" count="4">

          <property_set name="periodinfo">

            <property_simple key="format" value="HH:mm" />

            <property_simple key="weekday" value="4" name="Thursday" />

            <property_simple key="begin" value="06:00" />

            <property_simple key="end" value="17:00" />

          </property_set>

          <property_set name="periodinfo">

            <property_simple key="format" value="HH:mm" />

            <property_simple key="weekday" value="5" name="Friday" />

            <property_simple key="begin" value="06:00" />

            <property_simple key="end" value="17:00" />

          </property_set>

          <property_set name="periodinfo">

            <property_simple key="format" value="HH:mm" />

            <property_simple key="weekday" value="6" name="Saturday" />

            <property_simple key="begin" value="06:00" />

            <property_simple key="end" value="17:00" />

          </property_set>

          <property_set name="periodinfo">

            <property_simple key="format" value="HH:mm" />

            <property_simple key="weekday" value="7" name="7" />

            <property_simple key="begin" value="06:00" />

            <property_simple key="end" value="17:00" />

          </property_set>

        </property_collection>

      </property_set>

    </property_collection>

  </property_set>

  <property_set name="redirectrule" id="8cbb1c0f-f900-41a0-a455-c6b24dac336d">

    <property_simple key="id" value="8cbb1c0f-f900-41a0-a455-c6b24dac336d" />

    <property_cdata key="caption"><![CDATA[Неинтересные люди]]></property_cdata>

    <property_cdata key="description"><![CDATA[]]></property_cdata>

    <property_simple key="priority" value="2" />

    <property_simple key="enabled" value="1" />

    <property_simple key="onlyforredirectstate" value="0" />

    <property_simple key="cascaderedirect" value="0" />

    <property_simple key="numberdestination" value="31" />

    <property_simple key="userid" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8" />

    <property_simple key="currentstate" value="1" name="Enabled" />

    <property_collection name="extra" count="2">

      <property_set name="abonents" />

      <property_set name="time">

        <property_collection name="time" count="2">

          <property_set name="periodinfo">

            <property_simple key="format" value="HH:mm" />

            <property_simple key="weekday" value="6" name="Saturday" />

            <property_simple key="begin" value="03:00" />

            <property_simple key="end" value="13:00" />

          </property_set>

          <property_set name="periodinfo">

            <property_simple key="format" value="HH:mm" />

            <property_simple key="weekday" value="7" name="7" />

            <property_simple key="begin" value="03:00" />

            <property_simple key="end" value="13:00" />

          </property_set>

        </property_collection>

      </property_set>

    </property_collection>

  </property_set>

</data>

</oktellcommapper>

В случае, если раздел abonents пуст, это означает что правило применимо для всех вызовов.

Типы возможных дней недели (поле weekday):

public enum ECommType

{

Sunday = 0,        //Воскресенье
Monday = 1,        //Понедельник
Tuesday = 2,        //Вторник
Wednesday = 3,        //Среда
Thirsday = 4,        //Четверг
Friday = 5,        //Пятница
Saturday = 6        //Суббота

}

Типы возможных состояний правил переадресации (поле currentstate):

public enum ERedirectState

{

Disabled = 0,        //Отключеное
Enabled = 1,        //Включено
Active = 2        //Активно

}

Типы возможных абонентов, на которых назначено правило переадресации (поле type ветки abonent):

public enum ERedirectAbonentType

{

ExtNumber = 0,        //Внешний номер
User = 1,        //Пользователь
UserDepartment = 2,        //Отдел
Client = 3,        //Клиент
ClientGroup = 4        //Группа клиентов

}

void Redirect_SaveRule ( string xml ). Сохраняет на сервере и применяет передаваемое через XML-строку правило переадресации. В случае существования осуществляет горячую замену правила.

Формат передаваемого xml (на примере):

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="redirectrule">

  <property_set name="redirectrule">

    <property_simple key="id" value="8cbb1c0f-f900-41a0-a455-c6b24dac336d" />

    <property_cdata key="caption"><![CDATA[Неинтересные люди]]></property_cdata>

    <property_cdata key="description"><![CDATA[]]></property_cdata>

    <property_simple key="priority" value="2" />

    <property_simple key="enabled" value="1" />

    <property_simple key="onlyforredirectstate" value="0" />

    <property_simple key="cascaderedirect" value="0" />

    <property_simple key="numberdestination" value="31" />

    <property_simple key="userid" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8" />

    <property_simple key="currentstate" value="1" name="Enabled" />

    <property_collection name="extra" count="2">

      <property_set name="abonents">

  <property_collection name="abonents" count="2">

       <property_set name="abonent">

<property_simple key="type" value="1" name="usReady" />

        <property_simple key="number" value="4952778419" />

<property_cdata key="description"><![CDATA[Теща]]></property_cdata>

                 </property_set>

<property_set name="abonent">

<property_simple key="type" value="1" name="usReady" />

            <property_simple key="id" value="837afb4a-2be1-5ad3-9bba-1422f2dae0c7" />

<property_cdata key="description"><![CDATA[Иван Петрович]]></property_cdata>

                 </property_set>

  </property_collection>

</property_set>

      <property_set name="time">

        <property_collection name="time" count="5">

          <property_set name="periodinfo">

<property_simple key="format" value="HH:mm" />

            <property_simple key="weekday" value="1" name="Monday" />

        <property_simple key="begin" value="00:00" />

            <property_simple key="end" value="08:00" />

                 </property_set>

<property_set name="periodinfo">

<property_simple key="format" value="HH:mm" />

            <property_simple key="weekday" value="1" name="Monday" />

        <property_simple key="begin" value="18:00" />

            <property_simple key="end" value="23:59" />

                 </property_set>

<property_set name="periodinfo">

<property_simple key="format" value="HH:mm" />

            <property_simple key="weekday" value="2" name="Tuesday" />

        <property_simple key="begin" value="00:00" />

            <property_simple key="end" value="08:00" />

                 </property_set>

<property_set name="periodinfo">

<property_simple key="format" value="HH:mm" />

            <property_simple key="weekday" value="2" name="Tuesday" />

        <property_simple key="begin" value="18:00" />

            <property_simple key="end" value="23:59" />

                 </property_set>

<property_set name="periodinfo">

<property_simple key="format" value="HH:mm" />

            <property_simple key="weekday" value="0" name="Sunday" />

        <property_simple key="begin" value="00:00" />

            <property_simple key="end" value="23:59" />

                 </property_set>

        </property_collection>

      </property_set>

    </property_collection>

  </property_set>

</data>

</oktellcommapper>

void Redirect_SetEnabled ( string xml ). Меняет состояние активности для указанного в теле XML-строки правила переадресации.

Формат передаваемого xml (на примере):

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <property_set>

    <property_simple key="id" value="3145962b-2141-4b63-960e-9fb7142e0c7b" />

    <property_simple key="enabled" value="1" />

  </property_set>

</data>

</oktellcommapper>

void Redirect_DeleteRules ( string xml ). Удаляет указанные в теле XML-строки правила переадресации.

Формат передаваемого xml (на примере):

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <property_set>

    <property_simple key="id" value="3145962b-2141-4b63-960e-9fb7142e0c7b" />

    <property_simple key="id" value="cf8330f4-a0bf-4779-9539-ab8ea6c49df7" />

  </property_set>

</data>

</oktellcommapper>


Статистика коммутаций


Работа с логикой АТС

В этом разделе:

— Автодозвон, осуществление вызовов

— Работа с факсами

— События АТС по каналу пользователя

— Очередь ожидания

— Контент оппозитного канала

— Контент цепочки коммутаций

— Конференц-связь

Методы для работы с логикой АТС: набор номера, автодозвон, переключение

string CallNumber ( string number ). Запускает сервис автодозвона (при положенной трубке) или набора номера на текущей сессии (при поднятой трубке), в случае если все состояния допускают. Параметр в виде простой строки с номером. Вызов производится в следующем режиме: При наборе номер ищется сначала среди внутреннего номерного плана, в случае если обнаружен - набирается во внутренний номерной план, если нет - согласно прав доступа текущего пользователя к внешним линиям - вовне. Возвращает XML-строку с описанием ответа сервиса запускавшего набор номера или NULL, если до вызова логика прослойки зарезала команду. Общие примеры параметра и возвращающего значения чуть ниже в этом разделе.

string CallNumberEx ( string xml ). Запускает сервис автодозвона (при положенной трубке) или набора номера на текущей сессии (при поднятой трубке), в случае если все состояния допускают. Параметр в виде расширенного XML запроса. В теле запроса помимо номера (key="number") может быть установлено направление (key="direction", варианты: value="0" или name="city", value="1" или name="pbx", value="2" или name="undefined"). В случае пропуска номера или задания неопределенного направления вызов производится в следующем режиме: При наборе номер ищется сначала среди внутреннего номерного плана, в случае если обнаружен - набирается во внутренний номерной план, если нет - согласно прав доступа текущего пользователя к внешним линиям - вовне. Возвращает XML-строку с описанием ответа сервиса осущствлявшего обработку команды или NULL, если до вызова логика прослойки зарезала команду. Общие примеры параметра и возвращающего значения чуть ниже в этом разделе.

string SwitchNumber ( string number ). Осуществляет переключение (Flash и набор номера) при активной коммутации или набор номера при отсутствии коммутации (например из интерфейса внутреннего номерного плана). Параметр в виде простой строки с номером. При наборе номер ищется сначала среди внутреннего номерного плана, в случае если обнаружен - набирается во внутренний номерной план, если нет - согласно прав доступа текущего пользователя к внешним линиям - вовне. Возвращает XML-строку с описанием ответа сервиса осущствлявшего обработку команды или NULL,если до вызова логика прослойки зарезала команду. Общие примеры параметра и возвращающего значения чуть ниже в этом разделе.

string SwitchNumberEx ( string xml ). Осуществляет переключение (Flash и набор номера) при активной коммутации или набор номера при отсутствии коммутации (например из интерфейса внутреннего номерного плана). Параметр в виде расширенного XML запроса. В теле запроса помимо номера (key="number") может быть установлено направление (key="direction", варианты: value="0" или name="city", value="1" или name="pbx", value="2" или name="undefined"). В случае пропуска номера или задания неопределенного направления вызов производится в следующем режиме: При наборе номер ищется сначала среди внутреннего номерного плана, в случае если обнаружен - набирается во внутренний номерной план, если нет - согласно прав доступа текущего пользователя к внешним линиям - вовне. Возвращает XML-строку с описанием ответа сервиса осущствлявшего обработку команды или NULL, если до вызова логика прослойки зарезала команду.

Пример xml ответа сервера:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="callnumberresult" count="1">

  <property_set name="result">

    <property_simple key="code" value="0" name="cntStartedSuccessfully" />

  </property_set>

</data>

</oktellcommapper>

Пример xml запроса:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="callnumber">

  <property_set name="callnumber">

    <property_simple key="number" value="425" />

    <property_simple key="direction" name="pbx" />

  </property_set>

</data>

</oktellcommapper>

Типы возвращаемых кодов при старте вызовов через автодозвон:

public enum EACMAnswer

{

cntStartedSuccessfully  = 0, //Звонок успешно взят в реализацию
cntUserNotReady = 1,        //У осуществляющего вызов пользователя не найдены линии, готовые линии, или состояние кривое
cntBusy = 2,        //При звонке на внутренний номер - признак занятости. В очереди и сам повисеть может (в дальнейшем реализуем как раз ожидание в очереди...)
cntExtLineNotFound = 3,        //Не найдены готовые внешние линии (если будем на это замес делать.. возможно просто будет стоять и ждать.. )
cntError = 4,        //Прочие ошибки, исключения.
cntControlNotReady = 5,        //Режим не доделан.
cntNumberNotFound = 6        //Внутренний номер не найден (по факту, если сервак сам будет определять направление звонка, это вообще не будет задействовано)

}

Типы направлений вызовов, передаваемых в параметре direction:

public enum EOutcomingDirection

{

city = 0,        //Вызов на внешнее направление (в город или в АТС за внешними линиями)
pbx = 1,        //Вызов на внутреннее направление (внутренний номерной план сервера)
undefined = 2,        //Автоматическое определение. При наличии внутреннего номера - набор во внутреннее направление, при отсутствии внутреннего номера - во внешнее

}

bool DeclineCall ( ). Посылает на сервер АТС отказ от входящего вызова. Возвращается TRUE, если отказ принят системой. Сервер обрабатывает этот случай аналогично пропуску вызова по таймауту.

void AutoCallAbort ( ). Осуществляет остановку запущенного процесса автодозвона для авторизованного пользователя. В случае, если процесса автодозвона не обнаружено, или он перешел в фазу обработки в АТС (например, абонент снял трубку, и осуществляется обратный вызов пользователя), ничего не происходит.

ВНИМАНИЕ! В системе для одного пользователя может существовать только один процесс автодозвона. Любой последующий вызов без завершения предыдущего будет обрывать активную сессию и начинать ее с новыми параметрами заново.

Методы для работы с логикой АТС: факсимильные сообщения

bool FaxStartReceive ( string xml ). Запускает сеанс получения факсимильного сообщения на оппозитном канале коммутации. Команда может быть осуществлена только в момент коммутации при наличии у оппозитного канала возможности работы с факсимильными сообщениями. Для определения параметров и факта коммутации используется событие CommutationStarted канала OnCommunicate. В качестве параметра передается строка с XML форматированием, содержащим путь к файлу для сохранения после получения. В XML свойстве property_cdata ожидается значение ключа «filepath» и значении CDATA - пути к файлу. В случае, если файл существует, он будет перезаписан. Если факсимильное сообщение содержит несколько страниц, то каждая будет сохранена в указанном каталоге с добавлением в конец имени файла атрибута «_page» (то есть fn_page1.bmp, fn_page2.bmp и т.д.). Возвращает TRUE, если команда передана на сервер и FALSE, если текущие свойства и состояние канала не подходят.

Пример параметра:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="startfaxreceive">

  <property_set name="startfaxreceive">

    <property_cdata key="filepath"><![CDATA[C:\Принятые факсы\Договор_аренды.bmp]]></property_cdata>

  </property_set>

</data>

</oktellcommapper>

bool FaxStartTransmit ( string xml ). Запускает сеанс отправки факсимильного сообщения на оппозитном канале коммутации. Команда может быть осуществлена только в момент коммутации при наличии у оппозитного канала возможности работы с факсимильными сообщениями. Для определения параметров и факта коммутации используется событие CommutationStarted канала OnCommunicate. В качестве параметра передается строка с XML форматированием, содержащим пути к файлам, требующим отправки в контексте запускаемого сеанса. Возвращает TRUE, если команда передана на сервер и FALSE, если текущие свойства и состояние канала не подходят.

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="faxtransmit">

  <property_set name="faxtransmit">

    <property_cdata key="filepath" value="0"><![CDATA[C:\Принятые факсы\Договор_аренды_стр1.bmp]]></property_cdata>

    <property_cdata key="filepath" value="1"><![CDATA[C:\Принятые факсы\Договор_аренды_стр2.bmp]]></property_cdata>

    <property_cdata key="filepath" value="2"><![CDATA[C:\Принятые факсы\Договор_аренды_стр3.bmp]]></property_cdata>

  </property_set>

</data>

</oktellcommapper>

bool FaxStop (). Прерывает текущий сеанс факсимильного взаимодействия на оппозитном канале и возвращает канал в закоммутированное состояние с оппозитным каналом. Возвращает TRUE, если команда передана на сервер и FALSE, если текущие свойства и состояние канала не подходят.

События АТС по линии пользователя

События канала OnCommunicate (здесь) инициированные АТС для интерфейсного блока работы с телефоном и управления каналом:

CommutationStarted (231). Событие АТС о начале коммутации на канале устройства, связанного в карте с текущим рабочим местом. Среди параметров передается набор значений для отображения, флаг возможности использования встроенного факса для отправки факсимильных сообщений по оппозитному каналу. В случае звонка по задаче передаются имя и идентификатор задачи, а также лимит установленного в настройках задачи времени на обработку вызова (в секундах) и текущее время с начала обработки задачи (в секундах, для корректировки счетчика времени).

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="231" name="commutationstarted">

    <property_simple key="idchain" value="abcdef12-abcd-abcd-1234-1234567890ab" />

    <property_simple key="idconnection" value="12345678-1234-1234-1234-abcdef123456" />

    <property_simple key="canfax" value="1" />

    <property_simple key="opponentdescription" value="Иванов Сергей" />

    <property_simple key="opponentname" value="Иванов Сергей" />

    <property_simple key="opponentnumber" value="" />

    <property_simple key="opponentlineid" value="cf8330f4-a0bf-4779-9539-ab8ea6c49df7" />

    <property_simple key="opponentlinenumber" value="" />

  </event>

</data>

CommutationStopped (232). Событие АТС о разрыве коммутации на канале устройства, связанного в карте с текущим рабочим местом.

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="232" name="commutationstopped">

    <property_simple key="idchain" value="abcdef12-abcd-abcd-1234-1234567890ab" />

    <property_simple key="idconnection" value="12345678-1234-1234-1234-abcdef123456" />

  </event>

</data>

FaxStopped (233). Событие АТС о начале факс-сеанса на оппозитном канале. Может быть использовано для отображения в интерфейсе управления каналом команды остановки и возврата к коммутации с абонентом.

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="233" name="faxstarted">

    <property_simple key="description" value="4952217859" />

    <property_simple key="issending" value="0" />

    <property_simple key="idchain" value="abcdef12-abcd-abcd-1234-1234567890ab" />

  </event>

</data>

FaxStopped (234). Событие АТС о завершении факс-сеанса на оппозитном канале.

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="234" name="faxstopped">

    <property_simple key="idchain" value="abcdef12-abcd-abcd-1234-1234567890ab" />

  </event>

</data>

FaxFilesReceived (235). Событие АТС о завершении приема файлов по факс-сеансу на оппозитном канале. Содержит признак успешности или неудачи, а также весь перечень путей к файлам, куда сохранены принятые значения, или текст сообщения об ошибке.

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="235" name="faxfilesreceived">

    <property_simple key="success" value="1" />

    <property_simple key="errortext" value="" />

    <property_cdata key="requestedpath"><![CDATA[C:\Принятые факсы\Договор_аренды.bmp]]></property_cdata>

    <property_cdata key="filepath" value="0"><![CDATA[C:\Принятые факсы\Договор_аренды_page1.bmp]]></property_cdata>

    <property_cdata key="filepath" value="1"><![CDATA[C:\Принятые факсы\Договор_аренды_page2.bmp]]></property_cdata>

  </event>

</data>

</oktellcommapper>

RingStarted (236). Событие АТС о начале входящего вызова на линию пользователя. Может быть использовано для опроса и отображения очереди и/или контента оппозитного канала. А также для смены контента в режиме его отображения в случае, когда происходит смена ведущего канала вызывающей стороны.

Поле isconf определяет, инициирован ли текущий вызов менеджером конференций. Если да, то поле idconf содержит идентификатор конференции, в которую осуществляется приглашение; в противном случае поле отсутствует. Параметры конференции можно узнать по идентификатору путем использования методов раздела «Конференц-связь», название доступно также в поле callername параметра. Поля callerlineid, callerlinenum, calleruserid, callerdirection, callerid, callername. указывают на соответствующие описательные параметры вызывающего абонента, соответственно идентификатор линии, номер линии, идентификатор вызывающего пользователя, направление вызова, номер вызывающего абонента или номер комнаты конференции, имя вызывающего абонента или название конференции. Первые три из перечисленных полей не присутствуют в параметре, если осуществляется вызов из конференции.

Примеры:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="236" name="ringstarted">

    <property_simple key="idchain" value="abcdef12-abcd-abcd-1234-1234567890ab" />

    <property_simple key="isconf" value="1" />

    <property_simple key="idconf" value="12345678-1234-1234-1234-abcdef123456" />

    <property_simple key="callerdirection" value="conference" />

    <property_simple key="callerid" value="#144" />

    <property_simple key="callername" value="Совещание технического отдела" />

  </event>

</data>

</oktellcommapper>

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="236" name="ringstarted">

    <property_simple key="idchain" value="abcdef12-abcd-abcd-1234-1234567890ab" />

    <property_simple key="isconf" value="0" />

<property_simple key="callerlineid" value="cf2dd474-e2ab-3cad-561f-ab12cdef5678" />

    <property_simple key="callerlinenum" value="17016" />

    <property_simple key="calleruserid" value="09f78612-9408-4f69-b0e4-1357a37a3026" />

<property_simple key="callerdirection" value="oktell_pbx" />

    <property_simple key="callerid" value="31" />

    <property_simple key="callername" value="Зиннуров Альберт" />

  </event>

</data>

</oktellcommapper>

RingFinished (237). Событие АТС о прерывании входящего вызова на линию пользователя. Возникает только в том случае, когда вызываемый пользователь не снял трубку, а вызывающий абонент прервал вызов. В случае, если в очереди находятся несколько абонентов при прерывании вызова первого абонента данное событие не производится, однако производится повторное событие RingStarted с новым идентификатором цепочки.

Может быть использовано для скрытия полей/форм отображения контента и информации об абоненте.

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="237" name="ringfinished">

    <property_simple key="idchain" value="abcdef12-abcd-abcd-1234-1234567890ab" />

  </event>

</data>

</oktellcommapper>

ACMStarted (238). Событие АТС об активации автодозвона на канале пользователя.

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="238" name="acmstarted">

    <property_simple key="idchain" value="abcdef12-abcd-abcd-1234-1234567890ab" />

  </event>

</data>

</oktellcommapper>

ACMFinished (239). Событие АТС о деактивации автодозвона на канале пользователя.

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="239" name="acmfinished">

    <property_simple key="idchain" value="abcdef12-abcd-abcd-1234-1234567890ab" />

  </event>

</data>

</oktellcommapper>

FlashHoldAction (240). Событие АТС о смене состояния флеш-буфера канала пользователя. Генерируется сервером в клиентское приложение пользователя-владельца канала, когда производятся любые операции с флеш-буфером: поставлен на удержание другой канал, вызван из удержания и восстановлен в коммутации, переведен из удержания на другой объект, коммутацию, очередь, сценарий, отбит из буфера, или самостоятельно перешел в режим отбоя.

Возможные варианты действий (событий о смене состояния):

Put                = 1, //Размещен во флеш-буфере на удержание

Return        = 2, //Возвращен в коммутацию с каналом

Abort                = 3, //Удален из буфера по отбою канала-владельца

Lost                = 4, //Удален из буфера по собственной инициативе

Switch        = 5  //Переведен на другой объект в коммутацию или ожидание

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="240" name="flashholdaction">

    <property_simple key="action" value="1" name="put" />

    <property_simple key="idchain" value="abcdef12-abcd-abcd-1234-1234567890ab" />

  </event>

</data>

</oktellcommapper>

ChainStateChange (241). Событие АТС о смене состояния регистрации линии пользователя в цепочке коммутаций. Связывание с цепочкой (type = 1) и отвязка от цепочки (type = 2).

Отвязка в ситуации, когда вызывающий абонент прекратил дозвон, а анализатор очереди не обнаруживает элементов, возникает совместно с RingFinished. В общем случае генерируется чаще. Однако стоит иметь в виду, что в некоторых случаях канал может быть возвращен в обработку той же цепочки. В случае, если событие указывает о выходе из цепочки, дополнительное свойство «ishandled» будет указывать, произошло это по причине снятия трубки другим каналом группового номера (значение «1», «handled»), или нет (значение «0», «lost»).

Пример 1:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="241" name="chainstatechange">

    <property_simple key="idline" value="123dbaf4-12ab-34cd-56ef-ab12cdef5678" />

    <property_simple key="idchain" value="abcdef12-abcd-abcd-1234-1234567890ab" />

    <property_simple key="type" value="1" name="enter" />

  </event>

</data>

</oktellcommapper>

Пример 2:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="241" name="chainstatechange">

    <property_simple key="idline" value="123dbaf4-12ab-34cd-56ef-ab12cdef5678" />

    <property_simple key="idchain" value="abcdef12-abcd-abcd-1234-1234567890ab" />

    <property_simple key="type" value="0" name="exit" />

    <property_simple key="ishandled" value="0" name="lost" />

  </event>

</data>

</oktellcommapper>

LineStateChange (242). Событие АТС о смене состояния линии пользователя. Практически все смены состояния (за исключением кризисных явлений вроде потери связи с сервером оборудования) пробрасываются через это событие.

Возможные состояния линии описаны в разделе «Работа со статусом пользователя. Допустимые состояния линии».

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="242" name="linestatechange">

    <property_simple key="idline" value="123dbaf4-12ab-34cd-56ef-ab12cdef5678" />

    <property_simple key="lstate" value="1" name="lsReady" />

  </event>

</data>

</oktellcommapper>

Методы для работы с логикой АТС: очередь ожидания

string Queue_GetCurrentItems ( string xml ). Возвращает мета-описание всех абонентов, находящихся в очереди текущего авторизованного пользователя. Элементы располагаются по убыванию комбинированного приоритета обработки (учитываются выставленный приоритет, направление вызова, а также текущее время ожидания в очереди). При авторизации пользователя с логином «testqueue» в возвращаемом XML-документе даже при фактическом отсутствии очереди постоянно находятся несколько тестовых элементов.

Формат возвращаемого xml (на примере):

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="queueitems" count="2">

  <property_set name="queueitem">

    <property_simple key="dateformat" value="dd.MM.yyyy HH:mm:ss" />

    <property_simple key="managedlineid" value="5ae8377b-d7f9-4a39-bb87-e25475aed097" />

    <property_simple key="objecttype" value="0" name="qotQueueLogic" />

    <property_cdata key="username"><![CDATA[Денис]]></property_cdata>

    <property_simple key="lenqueue" value="273000" />

    <property_simple key="srcelementid" value="1302eadd-7600-411e-9ffb-abf445ad8be6" />

    <property_simple key="queuesource" value="0" name="qsLineLogic" />

    <property_cdata key="department"><![CDATA[Руководство]]></property_cdata>

    <property_simple key="calledid" value="14" />

    <property_simple key="callerid" value="21" />

    <property_simple key="idobject" value="12345678-1234-1234-1234-12345678123a" />

    <property_simple key="userid" value="53c0f2d6-9216-4cc3-804f-678c89f12750" />

    <property_simple key="managedlinenum" value="1525" />

    <property_simple key="startqueuetime" value="21.08.2008 10:44:00" />

    <property_simple key="queuepriority" value="10" />

    <property_simple key="idchain" value="abcdef12-abcd-abcd-1234-1234567890ab" />

  </property_set>

  <property_set name="queueitem">

    <property_simple key="dateformat" value="dd.MM.yyyy HH:mm:ss" />

    <property_simple key="tasklistid" value="-1" />

    <property_simple key="idobject" value="12345678-1234-1234-1234-12345678123b" />

    <property_simple key="taskisoutput" value="0" />

    <property_simple key="managedlinenum" value="1001" />

    <property_simple key="userid" value="00000000-0000-0000-0000-000000000000" />

    <property_cdata key="taskname"><![CDATA[Прием входящих]]></property_cdata>

    <property_simple key="calledid" value="5109940" />

    <property_simple key="srcelementid" value="924849c3-851e-4f7c-9513-b63b35417396" />

    <property_simple key="username" value="" />

    <property_simple key="startqueuetime" value="21.08.2008 10:44:00" />

    <property_simple key="objecttype" value="0" name="qotQueueLogic" />

    <property_simple key="lenqueue" value="243000" />

    <property_simple key="callerid" value="89050213951" />

    <property_simple key="queuepriority" value="10" />

    <property_simple key="managedlineid" value="79c950f7-8ae5-48de-8264-520aa331960b" />

    <property_simple key="department" value="" />

    <property_simple key="taskid" value="f58b19a4-527a-4d7a-a3cd-bc1d85e1f45d" />

    <property_simple key="queuesource" value="4" name="qsIncomingTask" />

    <property_simple key="idchain" value="12345678-ab12-ab12-ef34-abcabc123123" />

  </property_set>

</data>

</oktellcommapper>

Типы направлений, по которым производится звонок на внутренней линии (поле objecttype):

public enum EQueueObjectType

{

qotQueueLogic = 0,        //Стандартный вызов из менеджера очередей внутренней АТС.
qotTaskLogic = 1,        //Вызов оператора из обработчика звонка задачи при наличии активного абонента, находящего на линии.
qotAutoCallLogic = 2,        //Обратный вызов пользователя из модуля автодозвона.
qotBackFlash = 3        //Обратный вызов пользователя из АТС для соединения с абонентом на удержании во FLASH-буфере.

}

Типы объектов, производящих дозвон до внутренних номеров (поле queuesource), то есть источники, использующие менеджер очередей АТС (направление qotQueueLogic):

public enum EQueueSource

{

qsLineLogic = 0,        //Другие линии, стандартная работа АТС.
qsIVR = 1,        //Сценарий IVR.
qsInnerTaskLogic = 2,        //Внутренние задачи (не используется)
qsAutoCallManager = 3,        //Автодозвон.
qsIncomingTask = 4        //Входящие задачи.

}

Типы возможных направлений вызова (поле direction в свойствах звонка и задач):

public enum ECallDirection

{

cdAbsent = 0,        //Не заданное направление.
cdIncoming = 1,        //Входящий вызов.
cdOutcoming = 2        //Исходящий вызов.

}

Типы возможных коммутаций (поле type в свойствах коммутаций):

public enum ECommType

{

None = 0,        //Не заданный тип.
Abonent = 1,        //Коммутация с абонентом
IVR = 2        //Коммутация с IVR

}

Методы для работы с логикой АТС: контент оппозитного канала

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

Контент линии очищается при завершении активной фазы работы канала и создается заново в начале нового вызова.

Среди параметров присутствует пользовательский текстовый параметр CUSTOMINFO. Через него может быть осуществлен обмен информацией между пользователями каналов, с которыми производится коммутация или просто некоторое взаимодействие внешнего абонента на протяжении периода активности.

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

1) линия, находящаяся в коммутации с линией пользователя;

2) линия, находящаяся во флеш-буфере линии пользователя;

3) линия, осуществляющая входящий вызов на линию пользователя;

4) линия, находящаяся во флеш-буфере линии, осуществляющей вызов линии пользователя.

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

bool Content_SetOppositeCustom ( int destination, string custom ). Устанавливает значение пользовательского поля CUSTOMINFO контента оппозитного канала. Параметр destination указывает направление оппозитного канала, параметр custom определяет новое значение поля CUSTOMINFO. В случае успешного задания возвращается TRUE. В случае любого неуспешного исхода (отсутствия канала по указанному направлению, необнаружения внешней линии, несоответствии прав доступа, исключительных ситуациях) возвращается FALSE.

string Content_GetOppositeCustom ( int destination ). Возвращает значение пользовательского поля CUSTOMINFO контента оппозитного канала. Параметр destination указывает направление оппозитного канала. Возвращает строку со значением поля в простом виде.

string Content_GetOppositeFull ( int destination ). Возвращает полный контент оппозитного канала в XML-формате. Параметр destination указывает направление оппозитного канала. Возвращает строку с XML-содержимым контента в простом виде.

Пример содержимого контента:

<?xml version="1.0" encoding="utf-16"?>

<content Version="80903">

<call commcount="2" taskcount="1">

  <property_simple key="datetimeformat" value="dd.MM.yyyy HH:mm:ss" />

  <property_simple key="direction" value="1" name="cdIncoming" />

  <property_simple key="lineid" value="4741e765-f89d-47b2-89f7-0dcd619a8385" />

  <property_simple key="linenumber" value="12001" />

  <property_simple key="callerid" value="Номер не определен" />

  <property_simple key="calledid" value="5109805" />

  <property_simple key="idchain" value="70e29721-165a-4793-97c2-15a4d014d3f1" />

  <property_cdata key="custominfo"><![CDATA[]]></property_cdata>

  <property_simple key="timestart" value="04.09.2008 17:14:30" />

  <property_simple key="timestop" value="04.09.2008 17:14:44" />

  <property_simple key="totalsec" value="13" />

  <activity>

    <commutation index="0">

      <property_simple key="idconnection" value="43ac1678-75bb-4e41-8408-e5c01b60e303" />

      <property_simple key="type" value="2" name="IVR" />

      <property_simple key="timestart" value="04.09.2008 17:14:31" />

      <property_simple key="timestop" value="04.09.2008 17:14:33" />

      <property_simple key="totalsec" value="1" />

      <property_simple key="ivrscriptname" value="Телефонные системы. Вход." />

    </commutation>

    <task index="0">

      <property_simple key="effortid" value="23949836-b72c-4e4b-8be5-eef806a9cbb6" />

      <property_simple key="direction" value="1" name="cdIncoming" />

      <property_simple key="taskid" value="ad76a31a-e661-42a4-a8d5-8365623916cb" />

      <property_simple key="taskname" value="Входящий в телефонные системы" />

      <property_simple key="taskcode" value="" />

      <property_simple key="projectid" value="ab37c6e6-e983-458a-8621-5e0921ade3d1" />

      <property_simple key="tag" value="0" />

      <property_simple key="timeonline" value="04.09.2008 17:14:32" />

      <property_simple key="joinedtableid" value="-1" />

      <property_simple key="timestart" value="04.09.2008 17:14:32" />

      <commutation index="1">

        <property_simple key="idconnection" value="fc8cd4ff-b8b0-48b6-aeb1-662090bfd7d6" />

        <property_simple key="type" value="1" name="Abonent" />

        <property_simple key="timestart" value="04.09.2008 17:14:33" />

        <property_simple key="timestop" value="04.09.2008 17:14:41" />

        <property_simple key="totalsec" value="8" />

        <abonents count="1">

          <abonent index="1">

            <property_simple key="lineid" value="254aa1fc-4e18-4ad3-99ea-eb52417dd5a2" />

            <property_simple key="linenumber" value="16016" />

            <property_simple key="callerid" value="" />

            <property_simple key="userid" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8" />

            <property_simple key="username" value="Нигметзянов Шамиль" />

          </abonent>

        </abonents>

      </commutation>

    </task>

  </activity>

</call>

</content>

Методы для работы с логикой АТС: контент цепочки коммутаций

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

Коммутация - единичное соединение двух любых каналов в общий дуплексный голосовой обмен. У каждой коммутации есть уникальный идентификатор (Guid). В ходе работы системы АТС при переводе звонка, при помещении на удержание и последующем восстановлении в коммутацию, несмотря на то, что закоммутированные объекты и остаются теми же самыми, образованная повторная коммутация представляет собой иной объект с отличающимся набором свойств. В частности имеет другой идентификатор, другое время, другие файлы записи диалога. Коммутация в некотором смысле наиболее примитивный объект.

Звонок - понятие общее, даже несколько виртуализированное. В разных ситуациях звонком могут называться несколько отличающиеся сущности. Так например, с одной стороны звонок - это момент поступления вызова на внешнюю линию от абонента или факт осуществления вызова от одного пользователя другому. С другой стороны звонком может называться весь процесс обслуживания одного абонента: от поступления вызова, до отбоя его линии, включая все переключения, переводы звонка.

Наконец, наиболее общее понятие звонка в системе Oktell представлено понятием цепочки коммутаций. Она характеризуется уникальным идентификатором (Guid). Несколько коммутаций могут быть объединены в одну цепочку по признаку некоторой зависимости. Необходимость ввода такого более общего понятия обусловленена тем, что вызов абонента может повлечь целую серию коммутаций, удержаний, переводов, которые могут продолжаться даже после того, как сам абонент-инициатор из обработки вышел.

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

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

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

Цепочка характерна тем, что на протяжении ее существования принципиально не существует одновременных коммутаций. Все время делится на периоды закоммутированности двух каналов (или IVR)

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

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

В шапке контента имеется поле CUSTOM, предоставляемое для изменения из клиентского интерфейса пользователем, осуществляющим работу с каналом, участвующим в цепочке.

bool Chain_SetContentCustom ( string custom ). Устанавливает значение пользовательского поля CUSTOM контента цепочки коммутаций. Параметр custom определяет новое строковое значение поля CUSTOM. В случае успешного задания возвращается TRUE. В случае любого неуспешного исхода (неактивности канала пользователя, отсутствия цепочки, несоответствии прав доступа, исключительных ситуациях) возвращается FALSE.

string Chain_GetContentCustom ( ). Возвращает значение пользовательского поля CUSTOM контента цепочки коммутаций. Возвращает строку со значением поля в простом виде. В случае невозможности обратиться к контенту цепочки (неактивность канала пользователя, отсутствие цепочки, исключительные ситуации) возвращается NULL.

string Chain_GetContent ( ). Возвращает в XML-формате полный контент цепочки коммутаций, в которой участвует канал пользователя. Возвращает строку с XML-содержимым контента в простом виде. Каждая коммутация добавляет раздел commutationinfo, каждый вызов (за исключением прямого вызова сценариев IVR) добавляет раздел queueinfo. По мере развития цепочки все новые и новые вызовы размещаются в дереве элемента trace. Для получения и отображения в клиентском интерфейсе информации о вызывающем абоненте необходимо из дерева достать последнюю ветвь queueinfo.

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

Пример 1 простейшего содержимого контента (опрос в момент поступления/осуществления вызова):

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="chaincontent">

  <property_simple key="datetimeformat" value="dd.MM.yyyy HH:mm:ss" />

  <property_simple key="chainid" value="09fbde19-08ac-4e42-9476-11db421c3b0f" />

  <property_simple key="createtime" value="16.10.2008 17:57:01" />

  <property_simple key="calldirection" value="1" name="cdIncoming" />

  <property_cdata key="custom" />

  <property_collection count="1">

    <property_set id="trace">

      <property_collection count="1">

        <property_set name="queueinfo">

          <property_simple key="pbxdirection" value="0" name="internal" />

          <property_simple key="managedlineid" value="cf8330f4-a0bf-4779-9539-ab8ea6c49df7" />

          <property_simple key="objecttype" value="0" name="qotQueueLogic" />

          <property_simple key="username" value="z01" />

          <property_simple key="srcelementid" value="cf8330f4-a0bf-4779-9539-ab8ea6c49df7" />

          <property_simple key="queuesource" value="0" name="qsLineLogic" />

          <property_simple key="department" value="" />

          <property_simple key="calledid" value="" />

          <property_simple key="callerid" value="12" />

          <property_simple key="idobject" value="f42c8dd4-6e6b-4033-9349-5d51971fb251" />

          <property_simple key="userid" value="67e62e9a-a400-4f26-a1ac-b535e17a44f7" />

          <property_simple key="managedlinenum" value="15001" />

          <property_simple key="startqueuetime" value="16.10.2008 17:57:02" />

          <property_simple key="queuepriority" value="10" />

        </property_set>

      </property_collection>

    </property_set>

  </property_collection>

</data>

</oktellcommapper>

Пример 2 простейшего содержимого контента (опрос в момент первой коммутации в цепочке):

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="chaincontent">

  <property_simple key="datetimeformat" value="dd.MM.yyyy HH:mm:ss" />

  <property_simple key="chainid" value="09fbde19-08ac-4e42-9476-11db421c3b0f" />

  <property_simple key="createtime" value="16.10.2008 17:57:01" />

  <property_cdata key="custom"><![CDATA[Содержимое контента]]></property_cdata>

  <property_simple key="calldirection" value="1" name="cdIncoming" />

  <property_collection count="1">

    <property_set id="trace">

      <property_collection count="2">

        <property_set name="queueinfo">

          <property_simple key="pbxdirection" value="0" name="internal" />

          <property_simple key="managedlineid" value="cf8330f4-a0bf-4779-9539-ab8ea6c49df7" />

          <property_simple key="objecttype" value="0" name="qotQueueLogic" />

          <property_simple key="username" value="z01" />

          <property_simple key="srcelementid" value="cf8330f4-a0bf-4779-9539-ab8ea6c49df7" />

          <property_simple key="queuesource" value="0" name="qsLineLogic" />

          <property_simple key="department" value="" />

          <property_simple key="calledid" value="" />

          <property_simple key="callerid" value="12" />

          <property_simple key="idobject" value="f42c8dd4-6e6b-4033-9349-5d51971fb251" />

          <property_simple key="userid" value="67e62e9a-a400-4f26-a1ac-b535e17a44f7" />

          <property_simple key="managedlinenum" value="15001" />

          <property_simple key="startqueuetime" value="16.10.2008 17:57:02" />

          <property_simple key="queuepriority" value="10" />

        </property_set>

        <property_set name="commutationinfo" id="e1a5efef-3a37-4f46-8646-207175cfa4df">

          <property_simple key="id" value="e1a5efef-3a37-4f46-8646-207175cfa4df" />

          <property_simple key="timestart" value="16.10.2008 17:57:02" />

          <property_simple key="timeanswer" value="16.10.2008 17:57:08" />

          <property_simple key="connectiontype" value="3" />

          <property_simple key="isrecorded" value="1" />

          <property_simple key="alineid" value="cf8330f4-a0bf-4779-9539-ab8ea6c49df7" />

          <property_simple key="alinenum" value="15001" />

          <property_simple key="anumberdialed" value="14" />

          <property_simple key="aoutnumber" value="" />

          <property_simple key="auserid" value="67e62e9a-a400-4f26-a1ac-b535e17a44f7" />

          <property_simple key="astr" value="z01" />

          <property_simple key="blineid" value="254aa1fc-4e18-4ad3-99ea-eb52417dd5a2" />

          <property_simple key="blinenum" value="16016" />

          <property_simple key="bnumberdialed" value="" />

          <property_simple key="boutnumber" value="14" />

          <property_simple key="buserid" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8" />

          <property_cdata key="bstr"><![CDATA[Петр]]></property_cdata>

        </property_set>

      </property_collection>

    </property_set>

  </property_collection>

</data>

</oktellcommapper>

Методы и события для работы с логикой АТС: конференц-связь

Подробно о режиме конференц-связи и решаемых этой функцией задачах в разделе «Клиентское приложение. Телефон. Конференц-связь» руководства к ПК «Oktell».

Все методы требуют обработки случая NULL-возвращаемого значения.

Возможные состояния участника конференции

public enum EConferenceState

{

Idle                                = 0        //Заявленный участник конференции, подлежащий вызову.

OnlineTalking                = 11        //Активный, микрофон включен

OnlineListener                = 12        //Активный, микрофон выключен

Offline                        = 13        //Активный, но не в коммутации (выключен управляющим)

Calling                        = 21        //Вызываемый в реальном времени

WaitingInQueue                = 22        //Вызываемый, вызов размещен в очереди его телефонной линии

Flashed                        = 23        //Держит конференцию во FLASH-буфере

Exited                        = 24        //Вышел (уже не участник)

EntranceRequest                = 25        //Вошел с ожиданием подтверждения входа (в закрытую конференцию)

MisInviteBusy                = 31        //Вызов номера неудачен - занято

MisInviteNotRespond        = 32        //Вызов номера неудачен - нет ответа

MisInviteTimeout                = 33        //Вызов номера неудачен - таймаут установленный

MisInviteStop                = 34        //Вызов номера неудачен - стоп (объект не подходит, переадресации и т.д.)

MisInviteAbort                = 35        //Вызов номера неудачен - обрыв вызова управляющим

MisInviteRefuse                = 36        //Вызов неудачен. Отказ от участия в конференции

}

Вся работа с режимом конференц-связи состоит в вызове методов для получения информации и проведения действий в конференциях и обработке событий для отслеживания изменений в состояниях конференций и их участников.

string Conf_GetConferenceList ( ). Возвращает XML-строку со списком конференций и их базовых свойств. Параметры возвращаемого значения соответствуют описанным ниже параметрам функции Conf_CreateConference.

Структура возвращаемого значения на примере:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="conferencelist" count="1">

<property_set name="conference">

  <property_simple key="id" value="09f78612-9408-4f69-b0e4-1357a37a3026" />

  <property_simple key="room" value="334" />

  <property_cdata key="name" value=""><![CDATA[Беседка]]></property_cdata>

  <property_simple key="description" value="" name="" />

  <property_simple key="accessmode" value="11" name="Free" />

  <property_simple key="isselector" value="0" />

  <property_cdata key="creator" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8"><![CDATA[Петр Александрович]]></property_cdata>

  <property_cdata key="director" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8"><![CDATA[Петр Александрович]]></property_cdata>

  <property_cdata key="timestart"><![CDATA[02.09.2009 14:28:54]]></property_cdata>

  <property_simple key="canvieweachother" value="1" />

  <property_simple key="everyonecaninvite" value="0" />

  <property_simple key="recordrights" value="2" name="Competitors" />

</property_set>

</data>

</oktellxmlmapper>

string Conf_GetConferenceCompetitors ( string xml ). Возвращает XML-строку со списком участников указанной конференции. В параметре передается XML-структура с идентификатором конференции (idconf). Свойства возвращаемого значения соответствуют описанным ниже свойствам метода Conf_GetConference.

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

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="getconferencecompetitors">

  <property_set name="conference">

    <property_simple key="idconf" value="b89a414a-c955-4a14-8c35-90b09fe9a8d6" />

  </property_set>

</data>

</oktellcommapper>

Структура возвращаемого значения на примере:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="competitorlist" count="1">

<property_set name="conference">

  <property_simple key="id" value="b89a414a-c955-4a14-8c35-90b09fe9a8d6" />

  <property_collection name="competitors" count="2">

   <property_set name="competitor">

    <property_simple key="id" value="ce5c877c-7c46-42a0-8430-11085b4e50d0" />

    <property_cdata key="user" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8"><![CDATA[Петр Засадович]]></property_cdata>

    <property_simple key="line" value="9fb5ed96-a2ae-4f7e-b658-2e61a6174f6f" name="16016" />

    <property_simple key="number" value="" />

    <property_simple key="intnumber" value="" />

    <property_simple key="extnumber" value="" />

    <property_simple key="state" value="11" name="OnlineTalking" />

    <property_simple key="wanttalk" value="0" />

   </property_set>

   <property_set name="competitor">

    <property_simple key="id" value="6394a950-855e-4311-b075-790768307350" />

    <property_cdata key="user" value="67e62e9a-a400-4f26-a1ac-b535e17a44f7"><![CDATA[Артур Пирожкович]]></property_cdata>

    <property_simple key="line" value="cf8330f4-a0bf-4779-9539-ab8ea6c49df7" name="15001" />

    <property_simple key="number" value="" />

    <property_simple key="intnumber" value="" />

    <property_simple key="extnumber" value="" />

    <property_simple key="state" value="11" name="OnlineTalking" />

    <property_simple key="wanttalk" value="0" />

   </property_set>

  </property_collection>

</property_set>

</data>

</oktellxmlmapper>

string Conf_GetFullCompetitorList ( ). Возвращает XML-строку с полным списком пользователей системы (объектов, доступных для приглашения в конференцию) и их состояний. Введено для реализации интерфейса управления приглашениями создателем или управляющим конференции. Может использоваться совместно с событием UserStateChanged (268) для отслеживания изменения состояний. В этом случае сначала необходимо осуществить подписку на направление 3 (метод Conf_HandleEvent), затем текущим методом получить начальные данные: перечень объектов и их состояния.

Структура возвращаемого значения на примере:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="possiblecompetitorlist" count="...">

<property_set name="user">

  <property_cdata key="id"><![CDATA[17e640e1-1d55-4e45-a193-0469cbcd2dce]]></property_cdata>

  <property_cdata key="name" value=""><![CDATA[Максим Дмитриевич]]></property_cdata>

  <property_cdata key="groupid"><![CDATA[c4e3b424-3048-4cce-a2e4-033c532a7d99]]></property_cdata>

  <property_cdata key="groupname" value=""><![CDATA[Программисты]]></property_cdata>

  <property_simple key="userstate" value="0" name="usDisconnected" />

  <property_simple key="islunch" value="0" />

  <property_simple key="isredirect" value="0" />

  <property_simple key="inconference" value="0" />

  <property_cdata key="conferenceid"><![CDATA[00000000-0000-0000-0000-000000000000]]></property_cdata>

  <property_simple key="state" value="0" name="Idle" />

</property_set>

...............

<property_set name="user">

  .....

</property_set>

</data>

</oktellxmlmapper>

bool Conf_CheckReserveNumber ( int roomid ). Проверяет, доступен (свободен) ли числовой код конференции (по-другому номер комнаты). Возвращает TRUE, если свободен, и FALSE, если занят.

int Conf_GetEmptyRoomNumber ( ). Возвращает случайный свободный числовой номер для организации конференции. Номер выдается в виде трехзначного числа. В случае, если на момент создания конференции номер будет уже занят, методом создания будет возвращен соответствущий результат.

string Conf_CreateConference ( string xml ). Осуществляет создание конференции с заданными параметрами и начинает вызов всех указанных участников (рассылает приглашения и вызывает телефонную линию). В качестве параметра передается структура, содержащая все параметры конференции, а также список участников, указанных в виде идентификаторов пользователей, линий или номеров. Возвращает XML-строку с одним из результатов: success, error, alreadyexists. Часть свойств можно переназначить впоследствии методом Conf_SetupConference, однако некоторые свойства могут быть заданы только при создании, например «Осуществлять запись звука». Метод доступен для выполнения только пользователям, имеющим соответствующую привелегию.

Свойства передаваемого параметра.

Раздел conference:

id - Guid-идентификатор конференции.

room - числовой номер комнаты

accessmode - режим доступа к конференции. 11 - свободный, 12 - по разрешению управляющего, 13 - закрытый.

isselector - тип конференции. 0 - простая конференция, 1 - селекторное совещание.

everyonecaninvite - право всех участников приглашать в конференцию сторонних абонентов. 0 - только управляющий может приглашать, 1 - все участники.

canvieweachother - режим просмотра участников конференции. 0 - всех участников видит только управляющий, а сами участники не видят друг друга, 1 - участники видят друг друга.

record - записывать звук в файл для последующего прослушивания из статистических модулей.

recordrights - право на доступ к записи разговора. 1 - только управляющий, 2 - все участники конференции, 3 - только указанные пользователи (в этом случае в XML-структуре должен присутствовать набор recordusers).

director - идентификатор пользователя, управляющего конференцией (не обязательно сам создатель).

name - название конференции.

description - описание конференции.

Раздел competitors:

Содержит коллекцию наборов, каждый из которых содержит информацию об одном приглашаемом участнике. Участник может быть указан идентификатором пользователя (iduser), идентификатором линии (idline), внутренним номером в системе (intnumber) или внешним номером (extnumber). Впоследствии методом Conf_Invite могут быть приглашены и иные участники. Прочие абоненты могут быть приглашены также путем FLASH-переключений и совместных входов методом Conf_Phone_InviteNow.

Раздел recordusers:

Содержит коллекцию наборов, каждый из которых указывает идентификатор пользователя (iduser), которому разрешен доступ к записи конференции для прослушивания. Используется только в случае, если тип доступа к записи разговора установлен в значение («3» - доступ имеют указанные пользователи). Может быть опущен.

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

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="conferencemetadata" count="3">

<property_set name="conference">

  <property_cdata key="id"><![CDATA[0bf2ddb3-adcb-4e88-ab64-6803056c6def]]></property_cdata>

  <property_simple key="room" value="155" />

  <property_simple key="accessmode" value="12" />

  <property_simple key="isselector" value="1" />

  <property_simple key="everyonecaninvite" value="1" />

  <property_simple key="canvieweachother" value="1" />

  <property_simple key="recordrights" value="3" />

  <property_cdata key="director"><![CDATA[da803f01-ea77-40fa-bc9d-e2efb36fd5a8]]></property_cdata>

  <property_cdata key="name"><![CDATA[Совещание отдела техподдержки]]></property_cdata>

  <property_cdata key="description"><![CDATA[]]></property_cdata>

</property_set>

<property_set name="competitors">

  <property_collection name="list" count="3">

   <property_set name="competitor">

    <property_cdata key="iduser"><![CDATA[da803f01-ea77-40fa-bc9d-e2efb36fd5a8]]></property_cdata>

   </property_set>

   <property_set name="competitor">

    <property_cdata key="iduser"><![CDATA[48038abc-3a2f-4625-a775-4bff61ffa32a]]></property_cdata>

   </property_set>

   <property_set name="competitor">

    <property_cdata key="iduser"><![CDATA[67e62e9a-a400-4f26-a1ac-b535e17a44f7]]></property_cdata>

   </property_set>

  </property_collection>

</property_set>

<property_set name="recordusers">

  <property_collection count="2">

   <property_set name="user">

    <property_cdata key="iduser"><![CDATA[5776c54c-c60d-4e48-b64c-9fa11a89f558]]></property_cdata>

   </property_set>

   <property_set name="user">

    <property_cdata key="iduser"><![CDATA[da803f01-ea77-40fa-bc9d-e2efb36fd5a8]]></property_cdata>

   </property_set>

  </property_collection>

</property_set>

</data>

</oktellxmlmapper>

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="result">

  <property_set name="result">

    <property_simple key="result" value="success" />

  </property_set>

</data>

</oktellcommapper>

string Conf_SetupConference ( string xml ). Осуществляет изменение параметров существующей конференции. Изменению подлежат не все исходные параметры конференции, а только название (name), описание (description), режим доступа (accessmode), тип (isselector), управляющий (director), права пользователей на управление и последующий доступ к записи. Возвращает XML-строку с одним из результатов: success, error, notfound, accessdenied. Метод доступен для выполнения только управляющему указанной конференции или создателю в его отсутствие.

Подробнее о параметрах в описании метода Conf_CreateConference.

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

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="conferencemetadata" count="2">

<property_set name="conference">

  <property_cdata key="id"><![CDATA[607f1660-47b1-496f-9907-b47072d66bc7]]></property_cdata>

  <property_simple key="accessmode" value="11" />

  <property_simple key="isselector" value="1" />

  <property_simple key="everyonecaninvite" value="0" />

  <property_simple key="canvieweachother" value="1" />

  <property_simple key="recordrights" value="2" />

  <property_cdata key="director"><![CDATA[da803f01-ea77-40fa-bc9d-e2efb36fd5a8]]></property_cdata>

  <property_cdata key="name"><![CDATA[Совещание отдела техподдержки]]></property_cdata>

  <property_cdata key="description"><![CDATA[]]></property_cdata>

</property_set>

</data>

</oktellxmlmapper>

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="result">

  <property_set name="result">

    <property_simple key="result" value="success" />

  </property_set>

</data>

</oktellcommapper>

string Conf_GetConference ( string xml ). Возвращает XML-структуру с настройками указанной конференции и перечень всех участников и их свойств. В случае неудачи возвращает XML-строку с результатом notfound. В передаваемом параметре указывается идентификатор интересующей конференции (idconf). Возвращаемое значение соответствует передаваемому параметру функции Conf_CreateConference, однако раздел competitors расширен и представляет более полную информацию о каждом участнике:

idcompetitor - идентификатор участника конференции. Присваивается на этапе подключения нового участника к конференции и сохраняется на протяжении всей сессии конференции за этим участником. Вне зависимости от того, является участник пользователем, или просто каналом, вызывался как внешний или внутренний номер, его идентификатор участника всегда существует. Взаимодействие с менеджером конференций другими управляющими методами должно происходить преимущественно с указанием этого кода участника.

idchain - идентификатор цепочки коммутаций. Цепочка коммутаций у каждого абонента, участвующего в конференции, уникальна. Следует иметь в виду, что при переключении на конференцию вместе с оппонентом из коммутации (метод Conf_Phone_InviteNow) у оппонента будет создаваться новый идентификатор цепочки коммутаций во избежание дубликата.

iduser - идентификатор пользователя.

idline - идентификатор линии, по которой подключен участник.

number - номер, по которому вызывался участник. Дублирует непустую информацию из полей intnumber и extnumber. Считается, что номер является неким визуальным идентификатором участника только в случае, если участник был приглашен по номеру (автодозвоном, или через АТС).

intnumber - внутренний номер, по которому вызывался участник.

extnumber - внешний номер, по которому вызывался участник.

state - текущее состояние участника конференции из приведенного выше перечисления EConferenceState.

wanttalk - состояние флага «Хочу сказать!».

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

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="getconference">

  <property_set name="getconference">

    <property_simple key="idconf" value="cf2dd474-e2ab-3cad-561f-ab12cdef5678" />

  </property_set>

</data>

</oktellcommapper>

Структура возвращаемого значения при успешном вызове на примере:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="conferencemetadata" count="3">

<property_set name="conference">

  <property_cdata key="id"><![CDATA[c2be4b81-008d-4c8d-bb0e-c636ac93e027]]></property_cdata>

  <property_simple key="room" value="724" />

  <property_simple key="name" value="" name="" />

  <property_simple key="description" value="" name="" />

  <property_simple key="accessmode" value="11" name="Free" />

  <property_simple key="isselector" value="1" />

  <property_simple key="record" value="1" />

  <property_cdata key="creator"><![CDATA[da803f01-ea77-40fa-bc9d-e2efb36fd5a8]]></property_cdata>

  <property_cdata key="director"><![CDATA[da803f01-ea77-40fa-bc9d-e2efb36fd5a8]]></property_cdata>

  <property_cdata key="timestart"><![CDATA[20090902 16:50:46]]></property_cdata>

  <property_simple key="canvieweachother" value="1" />

  <property_simple key="everyonecaninvite" value="0" />

  <property_simple key="recordrights" value="2" name="Competitors" />

</property_set>

<property_set name="competitors">

  <property_collection name="list" count="2">

   <property_set name="competitor">

    <property_cdata key="idcompetitor"><![CDATA[a3242bbf-718c-426c-837c-887ced525cc2]]></property_cdata>

    <property_cdata key="idchain"><![CDATA[2929a51e-d915-4568-93c7-f2661317d74b]]></property_cdata>

    <property_cdata key="iduser"><![CDATA[da803f01-ea77-40fa-bc9d-e2efb36fd5a8]]></property_cdata>

    <property_cdata key="idline"><![CDATA[9fb5ed96-a2ae-4f7e-b658-2e61a6174f6f]]></property_cdata>

    <property_simple key="number" value="" />

    <property_simple key="intnumber" value="" />

    <property_simple key="extnumber" value="" />

    <property_simple key="state" value="11" name="OnlineTalking" />

    <property_simple key="wanttalk" value="0" />

   </property_set>

   <property_set name="competitor">

    <property_cdata key="idcompetitor"><![CDATA[5820c285-f602-4bbe-98a4-1f0a9ef633b0]]></property_cdata>

    <property_cdata key="idchain"><![CDATA[00000000-0000-0000-0000-000000000000]]></property_cdata>

    <property_cdata key="iduser"><![CDATA[67e62e9a-a400-4f26-a1ac-b535e17a44f7]]></property_cdata>

    <property_cdata key="idline"><![CDATA[cf8330f4-a0bf-4779-9539-ab8ea6c49df7]]></property_cdata>

    <property_simple key="number" value="" />

    <property_simple key="intnumber" value="" />

    <property_simple key="extnumber" value="" />

    <property_simple key="state" value="12" name="OnlineListener" />

    <property_simple key="wanttalk" value="0" />

   </property_set>

  </property_collection>

</property_set>

<property_set name="recordusers" />

</data>

</oktellxmlmapper>

string Conf_StopConference ( string xml ). Завершает указанную конференцию, выводя из нее всех активных участников. Если управляющему, выходя, не требуется завершать конференцию, необходимо вызвать метод собственного отлучения Conf_ExitRequest. В параметре передается XML-структура с идентификатором конференции. Возвращает XML-строку с одним из результатов: success, error, notfound, accessdenied. Метод доступен для выполнения только управляющему указанной конференции или создателю в его отсутствие.

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

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="stopconference">

  <property_set name="conference">

    <property_simple key="idconf" value="cf2dd474-e2ab-3cad-561f-ab12cdef5678" />

  </property_set>

</data>

</oktellcommapper>

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="result">

  <property_set name="result">

    <property_simple key="result" value="success" />

  </property_set>

</data>

</oktellcommapper>

string Conf_SetVoiceParams ( string xml ). Осуществляет включение/выключение микрофона указанному участнику селекторного совещания. В случае, если конференция не является селекторным совещанием, метод не выполняется. Возвращает XML-строку с одним из результатов: success, error, notfoundcomp, notselector, notfoundcomp, accessdenied. В параметре передается идентификатор конференции (idconf), идентификатор участника (idcompetitor) и признак включенности микрофона (cantalk).

При необходимости можно также изменить признак активности динамика - возможности слушать (canlisten). Метод доступен для выполнения только управляющему указанной конференции или создателю в его отсутствие. Право на прослушивание имеет приоритет, и если отключена возможность слушать, то абонент переводится в состояние offline и теряет возможность говорить. Отключение динамика не используется собственным клиентским приложением Oktell.

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

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="setvoiceparams">

  <property_set name="setvoiceparams">

    <property_simple key="idconf" value="cf2dd474-e2ab-3cad-561f-ab12cdef5678" />

    <property_simple key="idcompetitor" value="51299a93-a47e-b5bf-3b0e-425a33c7a302" />

    <property_simple key="cantalk" value="1" />

    <property_simple key="canlisten" value="1" />

  </property_set>

</data>

</oktellcommapper>

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="result">

  <property_set name="result">

    <property_simple key="result" value="success" />

  </property_set>

</data>

</oktellcommapper>

void Conf_SetWantTalk ( string xml ). Осуществляет выставление/снятие у текущего участника конференции флага «Хочу сказать», если его микрофон отключен управляющим конференции. После успешного завершения метода все участники конференции, подписанные на событийное направление 2 (подробнее в описании метода Conf_HandleEvent), получат соответствующее событие ConferenceCompetitorStateChanged (263). В качестве параметра передается XML-структура с идентификатором конференции (idconf), и признаком снятие/установка (wanttalk).

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

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="setwanttalk">

  <property_set name="setwanttalk">

    <property_simple key="idconf" value="cf2dd474-e2ab-3cad-561f-ab12cdef5678" />

    <property_simple key="wanttalk" value="1" />

  </property_set>

</data>

</oktellcommapper>

string Conf_ExitRequest ( string xml ). Осуществляет выход или запрос на выход из конференции. Выход из конференции по инициативе самого участника может быть осуществлен также разрывом связи (опусканием трубки). После выхода из конференции все участники, подписанные на событийное направление 2 (подробнее в описании метода Conf_HandleEvent) получат соответствующее событие ConferenceCompositionChanged (262), а также событие ConferenceCompetitorStateChanged (263). В параметре передается XML-структура с идентификатором конференции (idconf). Возвращает XML-строку с одним из результатов: success, error, notfoundcomp, notselector, notfoundcomp, accessdenied. Метод может быть вызван любым участником конференции, в том числе управляющим.

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

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="exitrequest">

  <property_set name="conference">

    <property_simple key="idconf" value="cf2dd474-e2ab-3cad-561f-ab12cdef5678" />

  </property_set>

</data>

</oktellcommapper>

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="result">

  <property_set name="result">

    <property_simple key="result" value="success" />

  </property_set>

</data>

</oktellcommapper>

string Conf_ExitToUser ( string xml ). Осуществляет вывод из конференции указанного ее участника, отправляя ему отбой. Все остальные участники конференции, подписанные на событийное направление 2 (подробнее в описании метода Conf_HandleEvent) получат соответствующее событие ConferenceCompositionChanged (262), а также событие ConferenceCompetitorStateChanged (263). В параметре передается XML-структура с идентификатором конференции (idconf) и идентификатором участника (idcompuser), который может быть также непустым идентификатором пользователя или непустым идентификатором линии. Возвращает XML-строку с одним из результатов: success, error, notfound, accessdenied. Метод может быть вызван только управляющим конференцией или создателем в его отсутствие.

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

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="exittouser">

  <property_set name="exittouser">

    <property_simple key="idconf" value="cf2dd474-e2ab-3cad-561f-ab12cdef5678" />

    <property_simple key="idcompuser" value="51299a93-a47e-b5bf-3b0e-425a33c7a302" />

  </property_set>

</data>

</oktellcommapper>

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="result">

  <property_set name="result">

    <property_simple key="result" value="success" />

  </property_set>

</data>

</oktellcommapper>

string Conf_EntranceRequest ( string xml ). Осуществляет вход в конференцию, если она открыта. Телефонная линия пользователя получает в свою очередь вызов из конференции. Для закрытых конференций вход невозможеню. Если доступ к конференции осуществляется с разрешения управляющего, то метод осуществляет запрос на вход. Участники конференции, подписанные на событийное направление 2 (подробнее в описании метода Conf_HandleEvent) получат соответствующие события ConferenceCompositionChanged (262) и ConferenceCompetitorStateChanged (263), а управляющий и создатель получают дополнительно событие ConferenceEntranceRequest (264). После этого управляющий или создатель в его отсутствие могут разрешить или запретить вход в конференцию для участника. В параметре передается XML-структура с идентификатором конференции (idconf). Возвращает XML-строку с одним из результатов: error, notfound, accessdenied, alreadydone, entered, alreadyrequested, requested. Вызывается любым пользователем системы, которому по привилегиям доступен модуль конференций.

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

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="entrancerequest">

  <property_set name="conference">

    <property_simple key="idconf" value="cf2dd474-e2ab-3cad-561f-ab12cdef5678" />

  </property_set>

</data>

</oktellcommapper>

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="result">

  <property_set name="result">

    <property_simple key="result" value="requested" />

  </property_set>

</data>

</oktellcommapper>

string Conf_PermitEntranceFor ( string xml ). Разрешает/запрещает вход пользователю, запросившему вход в конференцию, доступ к которой осуществляется с разрешения управляющего. В параметре передается XML-структура с идентификатором конференции (idconf), идентификатором участника (idcompetitor) и признаком разрешения/запрета входа (permit). Возвращает XML-строку с одним из результатов: success, error, notfound, accessdenied, alreadydone. Метод доступен для выполнения только управляющим конференцией или создателем в его отсутствие.

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

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="permitresponse">

  <property_set name="permitresponse">

    <property_simple key="idconf" value="cf2dd474-e2ab-3cad-561f-ab12cdef5678" />

    <property_simple key="idcompetitor" value="51299a93-a47e-b5bf-3b0e-425a33c7a302" />

    <property_simple key="permit" value="1" />

  </property_set>

</data>

</oktellcommapper>

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="result">

  <property_set name="result">

    <property_simple key="result" value="success" />

  </property_set>

</data>

</oktellcommapper>

string Conf_Invite ( string xml ). Осуществляет приглашение в конференцию указанных объектов (пользователей, линий, номеров). Их телефонные каналы получают в свои очереди вызовы из конференции. В случае, если вызывается внешний номер, начинается его набор в соответствии с настройкой вызова быстрых номеров. Для организации маршрутов в Oktell необходимо настроить использование служебного сценария набора номера для набора быстрых и внешних номеров. В параметре передается XML-структура со списком приглашаемых участников. Для каждого из них указываются либо код пользователя (iduser), либо код линии (idline), либо внутренний номер в системе (intnumber), либо внешний номер (extnumber). Возвращает XML-строку с одним из результатов: success, error, notfound, accessdenied. Если в настройках конференции в разделе прав стоит разрешение всем участникам приглашать других абонентов, то метод доступен для выполнения всеми участниками конференции. В противном случае метод может быть вызван только управляющим конференцией или создателем в его отсутствие.

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

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="invite">

  <property_set name="conference">

    <property_simple key="id" value="cf2dd474-e2ab-3cad-561f-ab12cdef5678" />

  </property_set>

  <property_set name="competitors">

    <property_collection count="3">

      <property_set name="competitor">

        <property_simple key="iduser" value="09f78612-9408-4f69-b0e4-1357a37a3026" />

      <property_simple key="idline" value="09f78612-9408-4f69-b0e4-1357a37a3026" />

      <property_simple key="intnumber" value="09f78612-9408-4f69-b0e4-1357a37a3026" />

      <property_simple key="extnumber" value="5109940" />

        <property_simple key="cantalk" value="1" />

      </property_set>

      <property_set name="competitor">

        <property_simple key="iduser" value="51299a93-a47e-b5bf-3b0e-425a33c7a302" />

        <property_simple key="cantalk" value="0" />

      </property_set>

      <property_set name="competitor">

        <property_simple key="extnumber" value="5109940" />

        <property_simple key="cantalk" value="1" />

      </property_set>

    </property_collection>

  </property_set>

</data>

</oktellcommapper>

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="result">

  <property_set name="result">

    <property_simple key="result" value="success" />

  </property_set>

</data>

</oktellcommapper>

void Conf_HandleEvent ( string xml ). Осуществляет подписку/отписку на событийные направления. Подписывать направление следует при необходимости получать события соответствующего направления. После устранения такой необходимости событийное направление следует отключить повторным вызовом метода с параметром «отписать» во избежание загрузки системы ресурсоемким порожняком.

Серверный менеджер управления конференциями генерирует несколько событий для обработки клиентскими приложениями. В соответствии с решаемыми задачами события объединены в группы (подробнее ниже в этом разделе «события, инициированные менеджером конференций»). Часть событий генерируются для управляющего конференцией, находящемся в режиме создания/настройки, часть для участников конференций, часть для всех, остальные редки. Поэтому с целью исключить массовую загрузку системы (серверного процессора, клиентских компьютеров, сети) рассылкой сообщений и их обработкой реализован механизм подписки на интересующие направления. Так, например, в свободном состоянии или в коммутациях, не связанных с конференциями, пользователю не интересны никакие события (возможно достаточно получать только события об изменении состава конференций для отображения). При загрузке модуля управления конференциями осуществляется подписка на события направления 1 (изменения списка и свойств конференций). При входе в конференцию участнику может оказаться необходимым получать дополнительно события об изменении состава участников этой конференции и их состояний (событийной направление 2). Создателю и управляющему при активации режима приглашения других участников может понадобиться обработка изменения состояния всех пользователей/объектов системы - самое ресурсоемкое событие. После устранения потребности в обработке событий соответствующего направления, крайне желательно отписать клиентское приложение от рассылки.

В параметре передается код направления (eventtype) и признак «подписать»/«отписать» (handle). Для направления «2» необходимо также передать идентификатор конференции (idconf).

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

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="handle">

  <property_set name="handle">

    <property_simple key="idconf" value="cf2dd474-e2ab-3cad-561f-ab12cdef5678" />

    <property_simple key="eventtype" value="2" />

    <property_simple key="handle" value="1" />

  </property_set>

</data>

</oktellcommapper>

string Conf_Phone_CheckCanInviteNow ( ). Определяет, является ли текущая коммутация конференцией (cansendconfinvite), и дополнительно, разрешено ли в данной коммутации совместное переключение в конференцию, находящуюся во FLASH-буфере пользователя (canswitchtogather). Метод имеет смысл вызывать однократно после получения события CommutationStarted (231). Возвращается XML-структура с двумя описанными параметрами.

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="info">

  <property_set name="info">

    <property_simple key="canswitchtogather" value="0" />

    <property_simple key="cansendconfinvite" value="1" />

  </property_set>

</data>

</oktellcommapper>

void Conf_Phone_InviteNow ( ). Осуществляет переключение в конференцию совместно с оппозитным абонентом. Работает в случае, если в момент коммутации во FLASH-буфере линии пользователя находится активная конференция. После вызова оба абонента попадают в конференцию.

ВНИМАНИЕ! Вызов метода приводит к несовсем корректному результату, если пользовательское рабочее место оснащено IP-телефоном, и переход во FLASH осуществлялся с использованием кнопки HOLD с последующим вызовом оппонента по 2-му транку.

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

События канала OnCommunicate (здесь) инициированные менеджером конференций для интерфейсных блоков управления конференциями и телефона:

ConferenceListChanged                        = 261 //Событийное направление 1

ConferenceCompositionChanged                = 262 //Событийное направление 2

ConferenceCompetitorStateChanged        = 263 //Событийное направление 2

ConferenceEntranceRequest                = 264 //Без подписки

ConferenceEntranceDenied                = 265 //Без подписки

ConferenceEntrancePermitted                = 266 //Без подписки

ConferenceNotifyInvite                        = 267 //Без подписки

ConferenceUserStateChanged                = 268 //Событийное направление 3

ConferenceListChanged (261). Событие менеджера конференций об изменении состава конференций или изменении базового свойства одной из активных конференций. Применимо для изменения перечня конференций в интерфейсном модуле клиентского приложения. Генерируется только по подписке на направление «1» (подробнее в описании метода Conf_HandleEvent). В качестве параметра передает структуру с содержанием информации о всех конференциях и значениях их базовых свойств.

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

<event id="261" name="conferencelistchanged">

  <property_simple key="eventtype" value="1" name="ConfListChanged" />

  <property_collection name="conferencelist" count="1">

   <property_set name="conference">

    <property_simple key="id" value="09f78612-9408-4f69-b0e4-1357a37a3026" />

    <property_simple key="room" value="334" />

    <property_cdata key="name" value=""><![CDATA[Беседка]]></property_cdata>

    <property_simple key="description" value="" name="" />

    <property_simple key="accessmode" value="11" name="Free" />

    <property_simple key="isselector" value="0" />

    <property_cdata key="creator" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8"><![CDATA[Петр Александрович]]></property_cdata>

    <property_cdata key="director" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8"><![CDATA[Петр Александрович]]></property_cdata>

    <property_cdata key="timestart"><![CDATA[02.09.2009 14:28:54]]></property_cdata>

    <property_simple key="canvieweachother" value="1" />

    <property_simple key="everyonecaninvite" value="0" />

    <property_simple key="recordrights" value="2" name="Competitors" />

   </property_set>

  </property_collection>

</event>

</data>

</oktellcommapper>

ConferenceCompositionChanged (262). Событие менеджера конференций об изменении состава участников активной конференции. Применимо для изменения перечня участников конкретной конференции в интерфейсном модуле клиентского приложения. Генерируется только по подписке на направление «2» (подробнее в описании метода Conf_HandleEvent). В качестве параметра передает структуру с содержанием информации о конференции и всех текущих ее участниках.

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

<event id="262" name="conferencecompositionchanged">

  <property_simple key="eventtype" value="2" name="ConfCompositionChanged" />

  <property_collection name="competitorlist" count="1">

   <property_set name="conference">

    <property_simple key="id" value="b89a414a-c955-4a14-8c35-90b09fe9a8d6" />

     <property_collection name="competitors" count="2">

     <property_set name="competitor">

      <property_simple key="id" value="ce5c877c-7c46-42a0-8430-11085b4e50d0" />

      <property_cdata key="user" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8"><![CDATA[Петр Засадович]]></property_cdata>

      <property_simple key="line" value="9fb5ed96-a2ae-4f7e-b658-2e61a6174f6f" name="16016" />

      <property_simple key="number" value="" />

      <property_simple key="intnumber" value="" />

      <property_simple key="extnumber" value="" />

      <property_simple key="state" value="11" name="OnlineTalking" />

      <property_simple key="wanttalk" value="0" />

     </property_set>

     <property_set name="competitor">

      <property_simple key="id" value="6394a950-855e-4311-b075-790768307350" />

      <property_cdata key="user" value="67e62e9a-a400-4f26-a1ac-b535e17a44f7"><![CDATA[Артур Пирожкович]]></property_cdata>

      <property_simple key="line" value="cf8330f4-a0bf-4779-9539-ab8ea6c49df7" name="15001" />

      <property_simple key="number" value="" />

      <property_simple key="intnumber" value="" />

      <property_simple key="extnumber" value="" />

      <property_simple key="state" value="11" name="OnlineTalking" />

      <property_simple key="wanttalk" value="0" />

     </property_set>

    </property_collection>

   </property_set>

  </property_collection>

</event>

</data>

</oktellxmlmapper>

ConferenceCompetitorStateChanged (263). Событие менеджера конференций о смене состояния одним участником конференции. Применимо для корректировки состояний в перечне участников конкретной конференции в интерфейсном модуле клиентского приложения. Генерируется только по подписке на направление «2» (подробнее в описании метода Conf_HandleEvent). В качестве параметра передает структуру с содержанием полной информации о состоянии участника.

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

<event id="263" name="conferencecompetitorstatechanged">

  <property_simple key="eventtype" value="3" name="ConfCompetitorStateChanged" />

  <property_collection name="competitorstate" count="1">

   <property_set name="conference">

    <property_simple key="id" value="f9bc8a0a-934d-4ae6-9493-a981525c18fa" />

    <property_collection name="competitors" count="1">

     <property_set name="competitor">

      <property_cdata key="idcompetitor"><![CDATA[8b35764e-1778-42cb-9c90-3d6744df6618]]></property_cdata>

      <property_cdata key="idchain"><![CDATA[00000000-0000-0000-0000-000000000000]]></property_cdata>

      <property_cdata key="user" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8"><![CDATA[Петр Александрович]]></property_cdata>

      <property_simple key="line" value="9fb5ed96-a2ae-4f7e-b658-2e61a6174f6f" name="16016" />

      <property_simple key="number" value="" />

      <property_simple key="intnumber" value="" />

      <property_simple key="extnumber" value="" />

      <property_simple key="state" value="23" name="Flashed" />

      <property_simple key="wanttalk" value="0" />

      <property_simple key="userstate" value="5" name="usFullbusy" />

      <property_simple key="linestate" value="128" name="lsFlash" />

     </property_set>

    </property_collection>

   </property_set>

  </property_collection>

</event>

</data>

</oktellxmlmapper>

ConferenceEntranceRequest (264). Событие менеджера конференций, возникающее в клиентском приложении управляющего и/или создателя, сгенерированное при запросе входа в конференцию нового участника. Актуально только для конференций с доступом по разрешению управляющего. Возникает безусловно и не требует предварительной подписки на направления методом Conf_HandleEvent.

В параметре передается идентифицирующая информация об участнике - пользователе или линии, в зависимости от того, откуда осуществляется вход. В любом случае присутствует указание идентификатора объекта (id) и его название (name), а также принадлежность к отделу (groupid, groupname).

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

<event id="264" name="conferenceentrancerequest">

  <property_simple key="eventtype" value="4" name="EntranceRequest" />

  <property_collection name="entrancerequest" count="1">

   <property_set name="user">

    <property_simple key="id" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8" />

    <property_cdata key="name" ><![CDATA[Артур Пирожкович]]></property_cdata>

    <property_simple key="groupid" value="9fb5ed96-a2ae-4f7e-b658-2e61a6174f6f" />

    <property_cdata key="groupname" ><![CDATA[Техподдержка]]></property_cdata>

    <property_simple key="userstate" value="1" name="usReady" />

   </property_set>

  </property_collection>

</event>

</data>

</oktellxmlmapper>

ConferenceEntranceDenied (265). Событие менеджера конференций, возникающее в клиентском прилолжении пользователя, который запросил вход в конференцию с доступом по разрешению управляющего. Указывает на запрет входа, выставленный управляющим в ответ на запрос. Возникает безусловно и не требует предварительной подписки на направления методом Conf_HandleEvent.

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

<event id="265" name="conferenceentrancedenied" />

</data>

</oktellxmlmapper>

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

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

<event id="266" name="conferenceentrancepermitted" />

</data>

</oktellxmlmapper>

ConferenceNotifyInvite (267). Событие менеджера конференций о проведении вызова текущего участника в конференцию. Ожидается, что при получении этого события клиентский модуль осуществит подписку на направление 2 и будет получать события об изменении состава участников конференции и их состояний. Отмена, прекращение вызова, смена состояний и другие события генерируются в направлении 2 (подробнее в описании метода Conf_HandleEvent). Текущий метод возникает безусловно и не требует предварительной подписки на направления.

Пример:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

<event id="267" name="conferencenotifyinvite">

  <property_simple key="eventtype" value="8" name="NotifyInvite" />

  <property_simple key="idconference" value="9fb5ed96-a2ae-4f7e-b658-2e61a6174f6f" />

</event>

</data>

</oktellxmlmapper>

ConferenceUserStateChanged (268). Событие менеджера конференций об изменении состояния любого пользователя или другого объекта системы, рассматриваемого в качестве возможного участника конференции. Поступают все изменения состояний на сервере, а также смена состояния в конференциях при сохранении состояния «FullBusy» самого пользователя. Генерируется для любого пользователя, подписанного на направление 3 (подробнее в описании метода Conf_HandleEvent). Рекомендуется использовать осмотрительно и только в крайних случаях - при создании конференции в режиме приглашения участников, а также при модификации конференций - после чего отписывать направление. Это будет гарантировать умеренную загрузку системы. Использовать необходимо совместно с методом Conf_GetFullCompetitorList: осуществить подписку, затем вызвать метод для получения начальных состояний всех объектов.

Пример 1 (смена состояния пользователя в системе):

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

   <event id="268" name="conferenceuserstatechanged">

     <property_simple key="eventtype" value="5" name="StateChanged" />

     <property_collection name="possiblecompetitorstate" count="1">

       <property_set name="user">

         <property_cdata key="id"><![CDATA[da803f01-ea77-40fa-bc9d-e2efb36fd5a8]]></property_cdata>

         <property_simple key="userstate" value="5" name="usFullbusy" />

       </property_set>

     </property_collection>

   </event>

</data>

</oktellcommapper>

Пример 2 (смена состояния участника конференции):

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

   <event id="268" name="conferenceuserstatechanged">

     <property_simple key="eventtype" value="5" name="StateChanged" />

     <property_collection name="possiblecompetitorstate" count="1">

       <property_set name="user">

         <property_cdata key="id"><![CDATA[da803f01-ea77-40fa-bc9d-e2efb36fd5a8]]></property_cdata>

         <property_simple key="inconference" value="1" />

         <property_cdata key="conferenceid"><![CDATA[dfc2a6c2-c03b-42ec-8ceb-37524ece34e9]]></property_cdata>

         <property_simple key="state" value="11" name="OnlineTalking" />

       </property_set>

     </property_collection>

   </event>

</data>

</oktellcommapper>


Работа с HAL

Методы для работы с HAL, управляющим локальным устройством

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

Пока не будет реализовано направление взаимодействия по каналу HAL или не установлен YEALINK телефон - звонить не получится даже после запуска и загрузки модуля. Хотя есть еще один вариант: запустить клиентское приложение октелл, выставить в нем параметры для гарнитуры, поставить галку использования перехватчика нажатий клавиатуры, после запустить COM и с нажатым ScrollLock будет доступно управление гарнитурой.

Вообще принцип работы устройства описан в мануале октелла в разделе "Клиентское приложение. Телефон" (или здесь). Управление через маппер сведено к 5 функциям и нескольким событиям, передающимся по вышеописанному каналу OnCommunicate (здесь). Также часть событий дублируется в виде событий Notify канала OnCommunicate (например "Зарегистрирована линия", "Подключено устройство", "Устройство потерялось" и т.п.) в полной аналогии с работой клиентского приложения oktell.

Методы

bool IsCurrentHALLocal ( ). Возвращает признак использования локального устройства (USB телефона или гарнитуры). TRUE - локальное устройство загружено, FALSE - не загружено (либо нет телефона вообще, либо устройство обслуживается сервером). Необходима для отображения и доступа к интерфейсу настройки локальног устройства с помощью нижепредставленных методов GetCurrentHALSettings и SetCurrentHALSettings.

bool IsCurrentHALHeadset ( ). Возвращает признак использования локального устройства - гарнитуры. TRUE, если текущее локальное устройство - гарнитура с софт управлением, FALSE - если USB телефон или модуль управления локальным устройством не используется. Необходима для отображения соответствующих интерфейсов софт-управления гарнитурой (кнопки поднять, положить трубку, цифровые клавиши с прямым набором в команды нижепредставленным методом SendLocalHALCommand().

string GetCurrentHALSettings ( ). Достает текущие настройки модуля поддержки локального устройства. Возвращает стандартную XML-строку с описанием текущих используемых параметров и списков возможных значений. В случае если модуль не запущен, либо не используется локальное устройство - возвращается NULL.

Формат возвращаемого значения (на примере). Структура постоянна - набор currentdevice, где каждый физический параметр представлен двумя параметрами XML - заголовком русским и собственно значением. Вообще, заголовки нужны только на этапе отладки, далее параметры динамически меняться не будут. Хотя можно поступить совершенно общим способом - все параметры сделать полностью динамическими, и в интерфейсе управляющего приложения выстраивать структуру на основе поставляемых данных, а не прописанную в коде.

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="halsettings" count="5">

  <property_set name="currentdevice">

    <property_cdata key="device_header"><![CDATA[Тип устройства]]></property_cdata>

    <property_cdata key="device"><![CDATA[Гарнитура]]></property_cdata>

    <property_cdata key="codec_header"><![CDATA[Кодек]]></property_cdata>

    <property_cdata key="codec"><![CDATA[0]]></property_cdata>

    <property_cdata key="waveout_header"><![CDATA[Динамик]]></property_cdata>

    <property_cdata key="waveout"><![CDATA[SoundMAX HD Audio]]></property_cdata>

    <property_cdata key="wavein_header"><![CDATA[Микрофон]]></property_cdata>

    <property_cdata key="wavein"><![CDATA[USB Audio Device]]></property_cdata>

    <property_cdata key="directx_header"><![CDATA[Использовать DirectSound]]></property_cdata>

    <property_cdata key="directx"><![CDATA[0]]></property_cdata>

    <property_cdata key="autohookup_header"><![CDATA[Снимать трубку автоматически]]></property_cdata>

    <property_cdata key="autohookup"><![CDATA[1]]></property_cdata>

    <property_cdata key="autohookuptimeoutsec_header"><![CDATA[Период ожидания до автоснятия, сек]]></property_cdata>

    <property_cdata key="autohookuptimeoutsec"><![CDATA[2]]></property_cdata>

    <property_cdata key="autohookdown_header"><![CDATA[Реагировать на отбой автоматически]]></property_cdata>

    <property_cdata key="autohookdown"><![CDATA[1]]></property_cdata>

    <property_cdata key="usekeyboard_header"><![CDATA[Разрешить управление с клавиатуры]]></property_cdata>

    <property_cdata key="usekeyboard"><![CDATA[1]]></property_cdata>

  </property_set>

  <property_set name="devicelist">

    <property_cdata key="name"><![CDATA[Доступные типы устройств]]></property_cdata>

    <property_collection name="available" count="4">

      <property_set name="device" id="0">

        <property_simple key="index" value="0" />

        <property_simple key="name" value="Гарнитура" />

      </property_set>

      <property_set name="device" id="1">

        <property_simple key="index" value="1" />

        <property_simple key="name" value="CyberPhone" />

      </property_set>

      <property_set name="device" id="2">

        <property_simple key="index" value="2" />

        <property_simple key="name" value="YealinkPhoneOCX" />

      </property_set>

      <property_set name="device" id="3">

        <property_simple key="index" value="3" />

        <property_simple key="name" value="Remote Yealink Phone OCX" />

      </property_set>

    </property_collection>

  </property_set>

  <property_set name="codeclist">

    <property_cdata key="name"><![CDATA[Доступные звуковые кодеки]]></property_cdata>

    <property_collection name="available" count="3">

      <property_set name="codec" id="0">

        <property_simple key="index" value="0" />

        <property_simple key="name" value="G.711 a-law (64 kbit/s)" />

      </property_set>

      <property_set name="codec" id="1">

        <property_simple key="index" value="1" />

        <property_simple key="name" value="G.711 mu-law (64 kbit/s)" />

      </property_set>

      <property_set name="codec" id="2">

        <property_simple key="index" value="2" />

        <property_simple key="name" value="MS GSM 6.10 (13 kbit/s)" />

      </property_set>

    </property_collection>

  </property_set>

  <property_set name="waveoutlist">

    <property_cdata key="name"><![CDATA[Доступные waveout звуковые устройства (динамики)]]></property_cdata>

    <property_collection name="available" count="2">

      <property_set name="waveoutdevice" id="0">

        <property_simple key="index" value="0" />

        <property_simple key="name" value="SoundMAX HD Audio" />

      </property_set>

      <property_set name="waveoutdevice" id="1">

        <property_simple key="index" value="1" />

        <property_simple key="name" value="USB Audio Device" />

      </property_set>

    </property_collection>

  </property_set>

  <property_set name="waveinlist">

    <property_cdata key="name"><![CDATA[Доступные wavein звуковые устройства (микрофоны)]]></property_cdata>

    <property_collection name="available" count="2">

      <property_set name="waveindevice" id="0">

        <property_simple key="index" value="0" />

        <property_simple key="name" value="SoundMAX HD Audio" />

      </property_set>

      <property_set name="waveindevice" id="1">

        <property_simple key="index" value="1" />

        <property_simple key="name" value="USB Audio Device" />

      </property_set>

    </property_collection>

  </property_set>

</data>

</oktellcommapper>

void SetCurrentHALSettings ( string xml ). Устанавливает новые настройки для модуля поддержки локального устройства.Может быть передано любое количество настроек. Пропущенные параметры заменятся текущими значениями, таким образом применены не будут. Параметр - Xml-строка установленного образца с элементом, аналогичным пункту дерева currentdevice в возвращаемой строке по запросу GetCurrentHALSettings, с пропущенными параметрами-заголовками.

Формат XML-параметра (на примере) команды на изменение свойств локального устройства. Любой параметр может быть опущен и будет подставлен автоматически из текущих значений. Перечень возможных вариантов для установки значений device, codec, wavein, waveout приходит в ответ на запрос метода GetCurrentHALSettings следом за набором currentdevice. В ходе работы возможные варианты не меняются, поэтому достаточно после запуска один раз опросить, а в дальнейшем применять. Хотя все же рекомендуется перед отображением интерфейса настройки осуществлять запрос, на основании которого предлагать возможные варианты пользователю.

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="halsettings">

  <property_set name="currentdevice">

    <property_cdata key="device"><![CDATA[Гарнитура]]></property_cdata>

    <property_cdata key="codec"><![CDATA[0]]></property_cdata>

    <property_cdata key="waveout"><![CDATA[SoundMAX HD Audio]]></property_cdata>

    <property_cdata key="wavein"><![CDATA[USB Audio Device]]></property_cdata>

    <property_cdata key="directx"><![CDATA[0]]></property_cdata>

    <property_cdata key="autohookup"><![CDATA[1]]></property_cdata>

    <property_cdata key="autohookuptimeoutsec"><![CDATA[2]]></property_cdata>

    <property_cdata key="autohookdown"><![CDATA[1]]></property_cdata>

    <property_cdata key="usekeyboard"><![CDATA[1]]></property_cdata>

  </property_set>

</data>

</oktellcommapper>

bool SendLocalHALCommand ( string xml ). Отправляет команду локальному модулю HAL, управляющему локальным устройством типа гарнитуры. Допускаются команды DTMF, Поднять трубку, Положить трубку, Генерировать флэш, Проиграть звуковой файл установленного формата (октелл сам использует только для тестов, но функция доступна). Возвращает TRUE, если допустимая команда найдена и исполнена, FALSE, если нет допустимых команд (не подошли по параметрам текущим, отсутствуют, неверно указаны в XML). Передаваемый в XML набор может содержать не одну команду, исполнена же будет первая корректно прошедшая парсинг и подошедшая по параметрам.

Для устройств, не являющихся локально управляемыми гарнитурами, в общем случае метод бессмысленен. Однако его функционал незначительно расширен, так, например, вызов FLASH и DTMF достигают АТС в любом случае при наличии какого-либо устройства. Дополнительно, вызов HOOKDOWN для устройств, отличных от гарнитур, обрывает текущий сеанс коммутации, а также производит остановку сервиса автодозвона, если он был запущен.

Коды команд:

hookup = 0,
hookdown = 1,
flash = 2,
dtmf = 3, (доп. параметр - символ DTMF)
playfile = 4, (доп. параметр - путь к файлу на воспроизведение)
mute = 5, (доп. параметр - «1»-выключить микрофон, «0»-включить микрофон)

Формат XML-параметра (на примерах) команды HAL на произведение действия. В теле команды дублированная информация - код и наименование. Первая, которая сможет быть удостоверенной и правильной, будет применена. Достаточно одного типа.

Для некоторых из команд требуется указание дополнительного параметра.

Пример 1:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="halcommand">

  <property_set name="halcommand">

    <property_simple key="name" value="dtmf" name="*" />

  </property_set>

</data>

</oktellcommapper>

Допускается вместо key="name" использовать key="code" с указанием целочисленного кода команды в атрибуте value:

<property_simple key="code" value="3" name="*" />

Пример 2:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="halcommand">

  <property_set name="halcommand">

    <property_simple key="name" value="hookup"/>

  </property_set>

</data>

</oktellcommapper>

Пример 3:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="halcommand">

  <property_set name="halcommand">

    <property_cdata key="name" value="playfile"><![CDATA[C:\1.wav]]></property_cdata>

  </property_set>

</data>

</oktellcommapper>

События

События канала OnCommutate (здесь) инициированные модулем работы с локальным устройством:

HALSrvRegSuccess (201). Событие без доп.параметров о факте успешной регистрации UDP канала Клиент-Сервер.

HALSrvRegTimeout (202). Событие без доп.параметров о таймауте регистрации UDP канала Клиент-сервер. Генерится не чаще 1 раза в 10 секунд.

HALDeviceFound (203). Событие с доп.параметром ("device" - название типа устройства) о факте обнаружения и успешной загрузки устройства.

HALDeviceLost (204). Событие без доп.параметров о факте потери локального устройства.

HALLightenKey (211). Событие с доп.параметром ("digit" - символ DTMF или служебный) о том что перехвачено нажатие на клавиатуре соответствующей кнопки и отправлено в HAL. Возможно бездейственно отправлено, так как нажатия ловятся всегда, а HAL принимает только в регламентированных случаях Служит для отображения подсветкой соответствующей кнопки интерфейса, а также для прописывания в поле набора номера. Возникает только при работе с гарнитурой.

HALHeadsetParams (212). Событие с доп.параметрами ("ishookup" - снята трубка, "isringing" - аппарат звенит ) при аппаратной смене одного из состояний гарнитуры. Возникает только при работе с гарнитурой.

HALClearNFieldNow (213). Событие без доп.параметров о необходимости очистить поле ввода номера в связи с изменением состояний. Возникает только при работе с гарнитурой.

HALClearNFieldNext (214). Событие с доп.параметром ("newvalue" 1, 0) о смене режима интерфейса набора номера. В силу того что номер может набираться параллельно с клавиатуры и перехватываться внизу, а также с интерфейса и передаваться по верхнему каналу, в некоторых случаях номер должен быть стерт в момент нажатия следующей кнопки безотносительно на каком уровне это происходит. Если требуемый режим снизу возникает - кидается событие HALClearNFieldNow, однако если наверху, то приложение должно знать о том что нужно вводить символ уже в чистое окно. Событие выставляет или снимает режим ожидания очистки при вводе очередного символа. Возникает только при работе с гарнитурой.


Обмен пользовательскими сообщениями

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

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

void Messaging_SendMessage ( string xml ). Производит формирование и отправку сообщения. Пользователь (или множество пользователей), а также тело сообщения формируются на основе переданного XML-параметра. Возможна отправка одному или нескольким пользователям. Идентификатор (поле id) не обязателен для указания, в случае его отсутствия будет присвоен автоматически. В случае отправки сообщения нескольким пользователям идентификатор в любом случае будет автоматически присвоен отдельно каждому сообщению.

Формат параметра на примере:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <property_set>

    <property_simple key="idmessage" value="a237bd24-cf31-3bb6-a140-b71782ec5d25" />

    <property_cdata key="text"><![CDATA[Текст сообщения 12312312312]]></property_cdata>

    <property_simple key="userid" value="d03a522f-b399-aa37-cb2a-943cf24d113e" />

    <property_simple key="userid" value="3B39F906-3C88-441D-AB9F-9C535F9FECE3" />

    <property_simple key="userid" value="CBA2395A-6D0B-469F-A76F-3884D6908A75" />

  </property_set>

</data>

</oktellcommapper>

void Messaging_SetViewed ( string xml ). Устанавливает для перечисленных в теле XML-параметра сообщений признак прочтения. В дальнейшем другие пользователи будут видеть статус сообщения - прочтено, время прочтения. Дополнительно при вызове метода получения всех новых сообщений эти сообщения не будут вновь передаваться.

Формат параметра на примере:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <property_set>

    <property_simple key="idmessage" value="a237bd24-cf31-3bb6-a140-b71782ec5d25" />

    <property_simple key="idmessage" value="DE609BC7-6D3B-4DAF-A418-A1D0648D7784" />

  </property_set>

</data>

</oktellcommapper>

string Messaging_GetAllNew ( ). Возвращает все поступившие сообщения за момент отсутствия (неавторизованности) пользователя. Сообщение перестает быть новым после установки для него признака прочтения.

Формат возвращаемого значения на примере:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <property_set>

    <property_simple key="datetimeformat" value="dd.MM.yyyy HH:mm:ss" />

    <property_simple key="id" value="a237bd24-cf31-3bb6-a140-b71782ec5d25" />

    <property_simple key="sentdate" value="27.07.2008 09:53:12" />

    <property_simple key="ismymessage" value="0" />

    <property_simple key="isold" value="0" />

    <property_cdata key="usera" value="d03a522f-b399-aa37-cb2a-943cf24d113e"><![CDATA[Петр]]></property_cdata>

    <property_cdata key="userb" value="3B39F906-3C88-441D-AB9F-9C535F9FECE3"><![CDATA[Виктор]]></property_cdata>

    <property_simple key="wasviewed" value="1" />

    <property_simple key="dtviewed" value="27.07.2008 10:05:25" />

    <property_cdata key="text"><![CDATA[Как дела?:)]]></property_cdata>

  </property_set>

</data>

</oktellcommapper>

string Messaging_GetLastForUser ( string xml ). Возвращает установленное количество последних сообщений в переписке с указанным пользователем.

Формат параметра на примере:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <property_set>

    <property_simple key="userid" value="d03a522f-b399-aa37-cb2a-943cf24d113e" />

    <property_simple key="count" value="3" />

  </property_set>

</data>

</oktellcommapper>

Формат возвращаемого значения на примере:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <property_set>

    <property_simple key="datetimeformat" value="dd.MM.yyyy HH:mm:ss" />

    <property_simple key="id" value="5F9D8A37-E65D-48AF-8BA6-F9191A8C1B2E" />

    <property_simple key="sentdate" value="12.08.2008 15:34:00" />

    <property_simple key="ismymessage" value="1" />

    <property_simple key="isold" value="1" />

    <property_cdata key="usera" value="d03a522f-b399-aa37-cb2a-943cf24d113e"><![CDATA[Петр]]></property_cdata>

    <property_cdata key="userb" value="3B39F906-3C88-441D-AB9F-9C535F9FECE3"><![CDATA[Виктор]]></property_cdata>

    <property_simple key="wasviewed" value="0" />

    <property_cdata key="text"><![CDATA[Проверка связи....)]]></property_cdata>

  </property_set>

  <property_set>

    <property_simple key="datetimeformat" value="dd.MM.yyyy HH:mm:ss" />

    <property_simple key="id" value="17611695-FC39-4B5C-A87D-999981D3A1FA" />

    <property_simple key="sentdate" value="26.07.2008 16:29:28" />

    <property_simple key="ismymessage" value="0" />

    <property_simple key="isold" value="1" />

    <property_cdata key="usera" value="3B39F906-3C88-441D-AB9F-9C535F9FECE3"><![CDATA[Виктор]]></property_cdata>

    <property_cdata key="userb" value="d03a522f-b399-aa37-cb2a-943cf24d113e"><![CDATA[Петр]]></property_cdata>

    <property_simple key="wasviewed" value="1" />

    <property_simple key="dtviewed" value="26.07.2008 16:29:28" />

    <property_cdata key="text"><![CDATA[Ок, счас]]></property_cdata>

  </property_set>

  <property_set>

    <property_simple key="datetimeformat" value="dd.MM.yyyy HH:mm:ss" />

    <property_simple key="id" value="73F38DE3-4883-4307-869E-9DD8BB518940" />

    <property_simple key="sentdate" value="26.07.2008 16:29:01" />

    <property_simple key="ismymessage" value="1" />

    <property_simple key="isold" value="1" />

    <property_cdata key="usera" value="d03a522f-b399-aa37-cb2a-943cf24d113e"><![CDATA[Петр]]></property_cdata>

    <property_cdata key="userb" value="3B39F906-3C88-441D-AB9F-9C535F9FECE3"><![CDATA[Виктор]]></property_cdata>

    <property_simple key="wasviewed" value="1" />

    <property_simple key="dtviewed" value="26.07.2008 16:29:19" />

    <property_cdata key="text"><![CDATA[Витька, зайдешь на минутку?]]></property_cdata>

  </property_set>

</data>

</oktellcommapper>

string Messaging_GetHistory ( string xml ). Возвращает все сообщения, удовлетворяющие фильтру в переданном XML-параметре. Поля datetimeformat, dtstart, dtstop, searchpattern могут быть неуказаны.

Формат параметра на примере:

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <property_set>

    <property_simple key="datetimeformat" value="dd.MM.yyyy HH:mm:ss" />

    <property_simple key="userid" value="d03a522f-b399-aa37-cb2a-943cf24d113e" />

    <property_simple key="dtstart" value="01.01.2008 00:00:00" />

    <property_simple key="dtstop" value="31.12.2008 23:59:59" />

    <property_cdata key="searchpattern"><![CDATA[строка для поиска по тексту сообщений]]></property_cdata>

  </property_set>

</data>

</oktellcommapper>

Формат возвращаемого значения аналогичен формату возврата метода Messaging_GetLastForUser.

event UserMessage (114). Событие канала OnCommunicate. Поступление сообщения от другого пользователя системы через внутренний мессенджер.

Пример:

?<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data>

  <event id="112" name="usermessage">

    <property_simple key="guid" value="37ccb224-ff71-3836-c410-a73782ef8d19" />

    <property_simple key="datetime" value="12.07.2008 20:29:11" />

    <property_simple key="senderid" value="d03a522f-b399-aa37-cb2a-943cf24d113e" />

    <property_cdata key="sendername"><![CDATA[Бочкарев Евгений]]></property_cdata>

    <property_cdata key="text"><![CDATA[Зайди плиз как освободишься..]]></property_cdata>

  </event>

</data>

</oktellcommapper>


Вспомогательные методы

Методы, используемые в ходе работы для получения наборов данных

string GetAllUsersInfo ( ). Возвращает информацию о всех пользователях системы. В теле возвращаемой XML-структуры содержатся такие значения как id, имя, логин, признак оператора, роль, текущее состояние и статус переадресации текущего авторизованного пользователя. Используется, например, при создании правил переадресации для указания пользователей, на которых распространяется правило.

Формат возвращаемого xml (на примере):

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="allusers" count="3">

  <property_set name="user" id="77579e8b-cd9a-43ca-b07e-1658220bbaae">

    <property_simple key="id" value="77579e8b-cd9a-43ca-b07e-1658220bbaae" />

    <property_simple key="type" value="1" name="utUser" />

    <property_cdata key="name"><![CDATA[Роман]]></property_cdata>

    <property_simple key="isoperator" value="1" />

    <property_simple key="group" value="c4e3b424-3048-4cce-a2e4-033c532a7d99" name="Программисты" />

    <property_cdata key="login"><![CDATA[xaka]]></property_cdata>

    <property_cdata key="role" value="cd90026f-f66d-4ca5-b182-66f2b94dbe1e"><![CDATA[<Индивидуальная роль>]]></property_cdata>

    <property_simple key="callerid" value="" />

    <property_cdata key="info"><![CDATA[]]></property_cdata>

  </property_set>

  <property_set name="user" id="59df4a16-df71-418e-97d1-2959d0c1198c">

    <property_simple key="id" value="59df4a16-df71-418e-97d1-2959d0c1198c" />

    <property_simple key="type" value="1" name="utUser" />

    <property_cdata key="name"><![CDATA[Владимир]]></property_cdata>

    <property_simple key="isoperator" value="0" />

    <property_simple key="group" value="2b5ff241-e876-4806-8455-0838cdab0358" name="Сметы" />

    <property_cdata key="login"><![CDATA[v]]></property_cdata>

    <property_cdata key="role" value="00000000-0000-0000-0000-000000000000" />

    <property_simple key="callerid" value="" />

    <property_cdata key="info"><![CDATA[]]></property_cdata>

  </property_set>

  <property_set name="user" id="fddcf3db-d543-48e3-a849-2d704365c5e3">

    <property_simple key="id" value="fddcf3db-d543-48e3-a849-2d704365c5e3" />

    <property_simple key="type" value="1" name="utUser" />

    <property_cdata key="name"><![CDATA[Игорь]]></property_cdata>

    <property_simple key="isoperator" value="0" />

    <property_simple key="group" value="c4e3b424-3048-4cce-a2e4-033c532a7d99" name="Программисты" />

    <property_cdata key="login"><![CDATA[Igor]]></property_cdata>

    <property_cdata key="role" value="00000000-0000-0000-0000-000000000000" />

    <property_simple key="callerid" value="" />

    <property_cdata key="info"><![CDATA[]]></property_cdata>

  </property_set>

</data>

</oktellcommapper>

Методы для работы с конфигурационными настройками

string ConfigGetAppSetting ( string key ). Возвращает строковое значение атрибута value по передаваемому в функцию ключу key из конфигурационного файла. Корректные непустые значения становятся доступны только после процедуры конфигурирования, запускаемой в начале тела метода ModuleStart.

string ConfigGetWorkDir ( ). Возвращает строку - путь к рабочей папке, где будут размещаться каталоги для обновлений, логи, временные папки и прочее. По умолчанию это папка со сборками COM-клиента Oktell. В отдельных случаях могут быть указаны иные варианты настройками файла конфигурации WORK_ROOTDIR и WORK_ROOTDIR_TYPE. Следует иметь в виду, что корректные рабочие значения выставляются только после процедуры конфигурирования, производимой в начале тела метода ModuleStart. В противном случае возвращаются значения по умолчанию, которые совпадают с правильными рабочими только в случае отсутствия указанных выше настроек конфигурации, либо их идентичностью.

string ConfigGetLiveUpdateDir ( ). Возвращает строку - путь к папке с обновлениями. По умолчанию это папка LiveUpdate в каталоге со сборками COM-клиента Oktell. В отдельных случаях могут быть указаны иные варианты настройками файла конфигурации WORK_ROOTDIR и WORK_ROOTDIR_TYPE. Следует иметь в виду, что корректные рабочие значения выставляются только после процедуры конфигурирования, производимой в начале тела метода ModuleStart. В противном случае возвращаются значения по умолчанию, которые совпадают с правильными рабочими только в случае отсутствия указанных выше настроек конфигурации, либо их идентичностью. Рекомендуется вызывать метод сразу после получения события о загрузке обновлений (после вызова ModuleStart).


Осуществление и прием вызовов

Возможные варианты работы с телефонной линией

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

а) С телефонного аппарата (аналогового или USB), связанного в карте с текущим компьютером;

б) С консоли управления телефоном (в клиентском приложении Oktell) или аналогично через реализованные методы управления гарнитурой (здесь);

в) Через методы автодозвона (подробнее здесь) с положенной трубкой подключенного телефона/гарнитуры (крайний случай, рекомендуемый к использованию только по назначению);

г) Через методы автодозвона (подробнее здесь) с поднятой трубкой подключенного телефона/гарнитуры (частный случай автодозвона, осуществляющий однократный набор номера).

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

В COM-оболочке существуют методы для полной настройки режима работы локального устройства: выбор типа, кодека, режимов автореагирования и т.д. Однако в целях удобства работы с телефонным аппаратом или гарнитурой, обслуживаемыми клиентским модулем HAL (модулем поддержки локального оборудования: USB или jack-гарнитур), а также распределения работ по интеграции, рекомендуется сначала настроить необходимый режим работы модуля HAL в клиентском приложении Oktell. В этом случае после выхода сохраненные значения будут применены при дальнейшем запуске в COM-объекте. Таким образом не придется предварительно описывать и разрабатывать настроечный блок, и можно будет сразу перейти к этапу совершения вызовов (например для гарнитуры с помощью вызова метода SendLocalHALCommand с поочередной передачей в него команд HOOKUP (снять трубку) и DTMF (звуковых тонов, соответствующих цифровым кнопкам). При активированном режиме управления гарнитурой с клавиатуры перехватом нажатых кнопок управление возможно производить вовсе без вызова команд COM-оболочки на более низком уровне, обеспечиваемым самим ядром COM-объекта.

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


Встраиваемые plugin-модули

В этом разделе:

— Принципы работы, архитектура

— Структура интерфейса

— Формат параметров и выходных значений

— Описание базовых элементов интерфейса

— Сервисное взаимодействие

— Рекомендации разработчику

— Объектная модель XML-парсера


Структура интерфейса

В главной сборке plugin-программы приложением Oktell ищется класс, реализующий нижеприведенный перечень методов. Если при подключении возникают проблемы с сопоставлением, модуль регистрации plugin-программы подскажет, что именно и в каком методе не подходит и не соответствует ожидаемому интерфейсу.

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

В этой статье приведен перечень методов, свойств и событий.

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

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

Методы, необходимые для соответствия интерфейсу

delegate string PluginQueryInvoker ( string xml );

Guid GetId ( );

int GetInterfaceVersion ( int lastknownversion );

string GetModuleVersion ( );

string GetModuleName ( );

string GetDBUpdate ( );

string GetForms ( );

string GetInputParams ( string xml );

string GetOutputParams ( string xml );

string ShowDesign ( string xml );

string PrepareShow ( string xml );

string GetCurrentFillInfo ( string xml );

string StopShow ( string xml );

string GetControlResult ( string xml );

System.Windows.Forms.Control CreateControl ( string xml );

event PluginQueryInvoker OnQuery;

string DoQuery ( string xml );


Формат параметров и выходных значений

Взаимодействие осуществляется методами и callback-методами с передачей параметров простых типов (BOOL, INT, STRING). В случае необходимости передачи большого числа параметров или сложных параметров используется строковый параметр, содержащий внутри себя XML-структуру. Строка XML установленного образца по умолчанию в кодировке UTF-16. Заголовки жестко фиксированы, содержимое согласно установленной структуре тэгов и их зависимостей, но произвольно по уровням вложенности и комбинациям.

<?xml version="1.0" encoding="utf-16"?>

<oktellcommapper version="80710">

<data name="" count="">

  <property_set name="" id="">

    <property_simple key="" value="" name="" />

    .....

    <property_simple key="" value="" name="" />

    <property_cdata key="" value=""><![CDATA[]]></property_cdata>

    .....

    <property_cdata key="" value=""><![CDATA[]]></property_cdata>

    <property_collection name="" count="">

      <property_set name="" id="">

         .....

      </property_set>

      .....

      <property_set name="" id="">

         .....

      </property_set>

    </property_collection>

  </property_set>

  .....

  <property_set name="" id="">

     .....

  </property_set>

</data>

</oktellcommapper>

Четыре основных тега внутренней структуры:

property_simple ( <property_simple key="" value="" name="" /> ) - элементарные свойства {key,value,name}, value и name могут отсутствовать. В целях уменьшения общего размера названия тегов и атрибутов могут быть сокращены так, что общий вид будет соответствовать ( <prs k="" v="" n="">...</prs> ).

property_cdata ( <property_cdata key="" value=""><![CDATA[...]]></property_cdata> ) - полнотекстовые свойства с неизвестным заранее содержимым {key,value,*cdata_text}, value может отсутствовать. В целях уменьшения общего размера названия тегов и атрибутов могут быть сокращены так, что общий вид будет соответствовать ( <prc k="" v=""><![CDATA[...]]></prc> ).

property_set ( <property_set name="" id="">...</property_set> ) - набор произвольного числа property_simple и property_cdata с допустимым присутствием одного тега property_collection. В целях уменьшения общего размера названия тегов и атрибутов могут быть сокращены так, что общий вид будет соответствовать ( <s n="" id="">...</s> ).

property_collection ( <property_collection name="" count="">...</property_collection> ) - коллекция произвольного числа property_set. В целях уменьшения общего размера названия тегов и атрибутов могут быть сокращены так, что общий вид будет соответствовать ( <с n="" cn="">...</c> ).

Базовый внешний тег <data> представляет собой аналог <property_collection>.

Очевидна объектная модель, лежащая в основе подобным образом организованной структуры. Рекомендация: не делать различий между property_simple и property_cdata при парсинге XML в объекты.

В статье «Объектная модель XML-парсера» приводится объяснение и формат взаимодействия с классами, обслуживающими XML-структуру описанного образца.


Описание базовых элементов интерфейса

Поскольку методы выполняются управляющим объектом plugin-программы, очевидно, что параметры в них готовятся приложением Oktell, а возвращаемые значения - самой plugin-программой. Поэтому при описании в текущем разделе возвращаемых значений методов везде пишется «возвращает...», а понимается «должно возвращаться...». Подробно формат и состав параметров приводится в дальнеших разделах. В текущем же разделе присутствует общее описание назначения методов.

· Общие модульные методы
· GetId
· GetInterfaceVersion
· GetModuleVersion
· GetModuleName
· GetDBUpdate
· GetForms
· Режим диалога
· GetInputParams
· GetOutputParams
· ShowDesign
· PrepareShow
· GetCurrentFillInfo
· StopShow
· GetControlResult
· Общие методы двух режимов
· CreateControl
· Сервисное взаимодействие
· OnQuery
· DoQuery

Общие модульные методы

Методы этого раздела служат для доступа к общей информации о plugin-программе, ее назначении и составе.

Guid GetId ( )

Возвращает уникальный Guid-идентификатор plugin-программы. Используется при различении программ и при обновлениях. По идентификатору приложение загружает plugin в память процесса и не допускает копий.

int GetInterfaceVersion ( int lastknownversion )

Возвращает версию интерфейса, на котором базируется plugin-программа.

В качестве параметра из Oktell передается максимально поздняя поддерживаемая версия. Изначально базовая версия 81022. Если plugin-программа при вызове метода возвращает номер версии, неизвестный для текущей версии Oktell, зарегистрировать ее не удастся.

string GetModuleVersion ( )

Возвращает версию plugin-программы в строковом виде. Например «A1.0.1».

string GetModuleName ( )

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

string GetDBUpdate ( )

Возвращает строку с запросом в формате Transact-SQL, представляющую собой пакет обновлений для БД при регистрации plugin-программы. Возможно присутствие нескольких батчей, разделенных строчками «GO» согласно tSQL. Запрос выполняется в БД в момент первого сохранения plugin-программы на сервере. Однако возможно и повторное исполнение в случае, если предварительно удалить регистрацию и создать новую с теми же параметрами. Это необходимо иметь в виду при создании запроса-обновления и формировать проверочные условия и/или удаляющие команды. Обновление для БД может отсутствовать. Однако для plugin-программ, реализующих доступ к уникальным сведениям в БД необходимо гарантировать существование в БД соответствующих таблиц, функций и хранимых процедур.

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

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="dbupdate" count="1">

  <property_set>

    <property_cdata key="sqltext"><![CDATA[if exists ( Select * FROM sysobjects where id = object_id ( 'dbo.T_PluginTest' ) )

  Drop Table dbo.T_PluginTest]]></property_cdata>

    <property_cdata key="sqltext"><![CDATA[Create table dbo.T_PluginTest (id int identity ( 1, 1 ) Primary Key, name nvarchar ( 50 ), st bit )]]></property_cdata>

    <property_cdata key="sqltext"><![CDATA[Insert into T_PluginTest ( Name, St ) Values ( 'A', 1 )]]></property_cdata>

  </property_set>

</data>

</oktellxmlmapper>

Текстовая информация из полей CDATA в каждом элементе property_cdata содержится отдельный batch-блок с запросом в формате tSQL. Все перечисленные запросы выполнятся поочередно в порядке присутствия в теле XML строки. Каждый запрос будет выполнен в отдельном batch-блоке. Если необходимо разделить текст запроса, представленного внутри одного property_cdata, необходимо стандарным способом в необходимом месте разделения вставить строку «GO».

Пример 2 возвращаемого значения.

Можно также возвращать строку, сразу содержащую тело запроса, в котором блоками GO разделяются batch-блоки.

if exists ( Select * FROM sysobjects where id = object_id ( 'dbo.T_PluginTest' ) )

  Drop Table dbo.T_PluginTest

GO

Create table dbo.T_PluginTest (id int identity ( 1, 1 ) Primary Key, name nvarchar ( 50 ), st bit )

GO

Insert into T_PluginTest ( Name, St ) Values ( 'A', 1 )

GO

string GetForms ( )

Возвращает перечень заявленных стартовых plugin-форм в виде строки с XML-содержимым установленной структуры. Для описания каждой plugin-формы используются параметры id, caption (name), description, controltype (control/form), module (dialog/crm), helplink. Именно этот метод определяет формат работы с plugin-программой. Настройка всех вариантов ее применения в комплексе зависит от состава стартовых plugin-форм и их направленности.

Каждая форма имеет уникальный Guid-идентификатор (id). Используется очевидным образом: Для настройки ссылок, а также для различения параметров (их принадлежности к конкретной форме при обмене информацией между plugin-программой и приложением Oktell). Название (caption) и описание (description) используются для отображения в приложении Oktell в модулях настройки на работу с plugin-программой.

Тип контрола (controltype) определяет в каком виде форма создана в теле plugin-программы, то есть экземпляром какого класса она является (в .NET это System.Windows.Forms.Control или System.Windows.Forms.Form, а в Win32 - имеет ли собственную рамку или встраивается в другие окна). В зависимости от этого приложение Oktell по-разному организует их отображение в диалоговом режиме. Оконные формы отображаются в собственной рамке, а контрольные размещаются в стандартном операторском диалоговом окне Oktell.

Первый рисунок - пример формы на базе Control, отображенной в режиме операторского диалога в стандартном для этого окне приложения Oktell.

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

Вариант использования (module) указывает приложению Oktell, где описываемую форму можно применять в настройках. Очевидно, одна и та же форма может в принципе быть использована в обоих режимах (операторские диалоговые окна и доступные через меню модули интерфейса). Но в описываемом интерфейсе взаимодействия производится их четкое разделение. Поэтому в случае подобной задачи на уровне объекта управления необходимо приложению Oktell указывать о наличии двух разных форм с разными идентификаторами, а при создании возвращать экземпляры одного класса. Возвращать же одни и те же экземпляры по запросам разных форм не рекомендуется, и делать необходимо крайне осмотрительно, так как при допущении ошибок в проекте итоговые окна могут исчезать и появляться в используемых местах непрогнозируемым способом.

Адрес справки (helplink) используется для режима модулей интерфейса и определяет веб-страницу (или раздел в файле справки), которая будет отображена при щелчке мышью на пиктограмму с вопросительным знаком в поле пункта меню главного окна клиентского приложения, соответствующего описываемой plugin-форме. Если адрес не задан, пиктограмма для пункта меню не отображается. Ссылка может быть адресом веб-страницей или веб-сервиса, а также ссылкой на раздел в некотором файле справки. Поиск файла будет осуществляться в основном каталоге клиентского приложения (его обновление производится стандартным способом через каталог LiveUpdate с обновлениями), и в каталоге с plugin-программой (для использования этого способа при регистрации plugin-программы через архив или вручную файл должен быть размещен в основной каталог plugin-программы). Примеры задания ссылки на автономно доступный файл справки: «plugin1_manual.chm», «manual.chm::/topic.htm#anchor», «form1.htm».

Пример возвращаемого значения.

В представленном примере из демонстрационной plugin-программы объявлены и реализованы пять стартовых plugin-форм: две для использования в диалоговом режиме и три для использования в режиме отображения внешних модулей.

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="availableforms" count="5">

  <property_set>

    <property_simple key="id" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />

    <property_cdata key="name"><![CDATA[Операторская форма 1]]></property_cdata>

    <property_cdata key="description"><![CDATA[Демонстрационная форма для диалогового режима на базе Form]]></property_cdata>

    <property_simple key="controltype" value="0" name="form" />

    <property_simple key="module" value="0" name="dialog" />

  </property_set>

  <property_set>

    <property_simple key="id" value="87b3e68e-8e27-4e1b-b3fa-d512f5c0148f" />

    <property_cdata key="name"><![CDATA[Операторская форма 2]]></property_cdata>

    <property_cdata key="description"><![CDATA[Демонстрационная форма для диалогового режима на базе Control]]></property_cdata>

    <property_simple key="controltype" value="1" name="control" />

    <property_simple key="module" value="0" name="dialog" />

  </property_set>

  <property_set>

    <property_simple key="id" value="817d77a7-5d0e-4783-9304-e310c2ac3443" />

    <property_cdata key="name"><![CDATA[Модуль 1]]></property_cdata>

    <property_cdata key="description"><![CDATA[Демонстрационный встраиваемый модуль образца 1 на базе Control]]></property_cdata>

    <property_simple key="controltype" value="1" name="control" />

    <property_simple key="module" value="1" name="crm" />

    <property_cdata key="helplink"><![CDATA[manual.chm::/topic_pluginABC.htm#form1]]></property_cdata>

  </property_set>

  <property_set>

    <property_simple key="id" value="38a86f47-073f-4ad7-a942-6919a048ab8a" />

    <property_cdata key="name"><![CDATA[Модуль 2]]></property_cdata>

    <property_cdata key="description"><![CDATA[Демонстрационный встраиваемый модуль образца 2 на базе Control]]></property_cdata>

    <property_simple key="controltype" value="1" name="control" />

    <property_simple key="module" value="1" name="crm" />

    <property_cdata key="helplink"><![CDATA[manual.chm::/topic_pluginABC.htm#form2]]></property_cdata>

  </property_set>

  <property_set>

    <property_simple key="id" value="03e57976-b970-45ff-aec2-fa95ef274bd7" />

    <property_cdata key="name"><![CDATA[Модуль 3]]></property_cdata>

    <property_cdata key="description"><![CDATA[Демонстрационный встраиваемый модуль образца 3 на базе Form]]></property_cdata>

    <property_simple key="controltype" value="0" name="form" />

    <property_simple key="module" value="1" name="crm" />

    <property_cdata key="helplink"><![CDATA[http://www.telsystems.ru/help/plugins/demoform3.htm]]></property_cdata>

  </property_set>

</data>

</oktellxmlmapper>

Режим диалога (операторские формы)

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

string GetInputParams ( string xml )

Возвращает перечень входных параметров для указанной формы.

Параметр представляет собой строку в XML формате, в которой присутствует Guid идентификатор plugin-формы.

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

Используется при настройке компонента plugin-форма в момент создания сценария диалога. Администратор, создающий сценарий, задает описанные входные значения на основе свойств, указанных в возвращаемой структуре. Возможные типы: аргументы (строковые, числовые, дата-время, общие), запросы к БД, возвращающие значения или наборы, а также перечислимые типы с возможными вариантами, описанными в структуре. В момент выполнения сценария при передаче управления компоненту Plugin-форма, выполняются вычисления всех установленных параметров, готовится XML структура, которая затем передается в плагин на отображение модуля.

Пример передаваемого параметра:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="inputparams" count="1">

  <property_set name="forminput">

    <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />

    <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />

  </property_set>

</data>

</oktellxmlmapper>

Возвращаемое значение.

Каждый параметр представляет собой отдельный набор property_set в основной коллекции. Задаваемые свойства:

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

paramtype - тип параметра. Определяет способ получения значения параметра при настройке в сценарии и тип значения. Допускается 7 вариантов (1-string, 2-int, 3-datetime, 4-argument, 5-table, 6-tablequery, 7-fixedlist).

· 1, 2, 3, 4 - задаются из формы аргумента, позволяющей выбрать константное значение, значение переменной, выражения или встроенной в диалоговый сценарий функции, различия лишь в ограничении на формат выходного значения (строка, число, строка с дата/время содержимым, произвольный аргумент).
· 5 - возвращает некоторый набор данных из БД, задается в формате SQL создателем сценария.
· 6 - аналогично возвращает из БД набор данных, однако задает «запрос по умолчанию». Указанный текст будет отображаться в поле ввода запроса у разработчика сценария в начале и каждый раз, когда он будет очищать это поле. Для указания текста запроса у соответствующего параметру элемента property_set задается коллекция, содержащая один подэлемент с именем «query». В нем должно присутствовать свойство property_cdata с ключом sqltext. Также допускаются свойства connectiontype, connectionstring, определяющие в случае указания соответственно направление подключения (Собственная БД, ADO, OLE, Oracle, ODBC) и строку подключения к БД. Этот тип параметра может быть использован в случае, если разработчики plugin-программы закладывают жесткую структуру взаимодействия с БД, и их квалификация существенно выше, чем у возможного разработчика сценария.
· 7 - фиксированный список. Предлагает разработчику выбрать один из описанных в теле параметра вариантов. Для этого в соответствующем элементе property_set задается коллекция из других элементов, описывающих возможные варианты значений. Каждый описательный набор property_set имеет атрибуты name="category" и id, установленный в соответствии с идентификатором варианта. В теле описательного набора присутствуют свойства с ключами id и name. id - определяет код, который будет передан как выбранный вариант при формировании значений для передачу в форму, name - название, которое увидит разработчик сценария в списке.

paramname - название параметра, которое увидит разработчик сценанрия.

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

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

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="input" count="6">

  <property_set>

    <property_simple key="paramkey" value="operator" />

    <property_simple key="paramtype" value="1" name="string" />

    <property_cdata key="paramname"><![CDATA[Оператор]]></property_cdata>

    <property_cdata key="paramdescription"><![CDATA[Имя текущего оператора]]></property_cdata>

  </property_set>

  <property_set>

    <property_simple key="paramkey" value="clientid" />

    <property_simple key="paramtype" value="2" name="int" />

    <property_cdata key="paramname"><![CDATA[Клиент]]></property_cdata>

    <property_cdata key="paramdescription"><![CDATA[Код обрабатываемого клиента]]></property_cdata>

   <property_simple key="paramextra" value="500" />

  </property_set>

  <property_set>

    <property_simple key="paramkey" value="queuetime" />

    <property_simple key="paramtype" value="4" name="argument" />

    <property_cdata key="paramname"><![CDATA[Время в очереди]]></property_cdata>

    <property_cdata key="paramdescription"><![CDATA[Будет отображено на форме без анализа]]></property_cdata>

  </property_set>

  <property_set>

    <property_simple key="paramkey" value="products" />

    <property_simple key="paramtype" value="5" name="table" />

    <property_cdata key="paramname"><![CDATA[Текущие товары]]></property_cdata>

    <property_cdata key="paramdescription"><![CDATA[Набор товаров запросом из БД (Id, Name, Set)]]></property_cdata>

  </property_set>

  <property_set>

    <property_simple key="paramkey" value="users" />

    <property_simple key="paramtype" value="6" name="tablequery" />

    <property_cdata key="paramname"><![CDATA[Пользователи]]></property_cdata>

    <property_cdata key="paramdescription"><![CDATA[Пользователи (Id, Name)]]></property_cdata>

    <property_collection name="query" count="1">

      <property_set name="query">

        <property_simple key="connectiontype" value="1" name="sql" />

        <property_simple key="connectionstring" value="" />

        <property_cdata key="sqltext"><![CDATA[Select Id, Name From A_Users]]></property_cdata>

      </property_set>

    </property_collection>

  </property_set>

  <property_set>

    <property_simple key="paramkey" value="categories" />

    <property_simple key="paramtype" value="7" name="fixedlist" />

    <property_cdata key="paramname"><![CDATA[Категории]]></property_cdata>

    <property_cdata key="paramdescription"><![CDATA[Направление работы]]></property_cdata>

    <property_collection name="categories" count="2">

      <property_set name="category" id="0">

        <property_simple key="id" value="0" />

        <property_cdata key="name"><![CDATA[Товары]]></property_cdata>

      </property_set>

      <property_set name="category" id="1">

        <property_simple key="id" value="1" />

        <property_cdata key="name"><![CDATA[Услуги]]></property_cdata>

      </property_set>

    </property_collection>

  </property_set>

</data>

</oktellxmlmapper>

string GetOutputParams ( string xml )

Возвращает перечень выходных параметров для указанной формы.

Параметр представляет собой строку в XML формате, в которой присутствует Guid идентификатор plugin-формы.

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

Используется при настройке компонента plugin-форма в момент создания сценария диалога. Администратор, создающий сценарий, указывает в какие переменные будут при выполнении сохранены значения описанных выходные параметров. В момент выполнения сценария после завершения выполнения компонента Plugin-форма, в указанные переменные попадут соответствующие значения выходных параметров.

Пример передаваемого параметра:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="outputparams" count="1">

  <property_set name="formoutput">

    <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />

    <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />

  </property_set>

</data>

</oktellxmlmapper>

Возвращаемое значение.

Каждый параметр представляет собой отдельный набор property_set в основной коллекции. Обязательными являются свойства:

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

paramtype - тип параметра. Определяет способ получения значения параметра при настройке в сценарии и тип значения. Допускается 4 варианта (1-string, 2-int, 3-datetime, 4-variable). Влияют на формат выбора переменной для сохранения значения. Соответственно для выбора предоставляется список только строковых переменных, только числовых, только переменных дата/время или список всех переменных.

paramname - название параметра, которое увидит разработчик сценанрия.

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

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="output" count="3">

  <property_set>

    <property_simple key="paramkey" value="selectedproduct" />

    <property_simple key="paramtype" value="2" name="int" />

    <property_cdata key="paramname"><![CDATA[Выбранный товар]]></property_cdata>

    <property_cdata key="paramdescription"><![CDATA[Код (id) выбранного товара]]></property_cdata>

  </property_set>

  <property_set>

    <property_simple key="paramkey" value="info" />

    <property_simple key="paramtype" value="4" name="variable" />

    <property_cdata key="paramname"><![CDATA[Текст уведомления]]></property_cdata>

    <property_cdata key="paramdescription"><![CDATA[Для отображения следующим компонентом в сценарии после завершения работы с формой]]></property_cdata>

  </property_set>

  <property_set>

    <property_simple key="paramkey" value="dt" />

    <property_simple key="paramtype" value="3" name="datetime" />

    <property_cdata key="datetimeformat"><![CDATA[dd.MM.yyyy HH:mm:ss]]></property_cdata>

    <property_cdata key="paramname"><![CDATA[Время]]></property_cdata>

    <property_cdata key="paramdescription"><![CDATA[Время, установленное для следующей связи]]></property_cdata>

  </property_set>

</data>

</oktellxmlmapper>

string ShowDesign ( string xml )

Вызывается для отображения диалоговой plugin-формы в «демонстрационном» режиме без передачи установленных для нее входных параметров.

В строковом параметре находится XML структура с указанием Guid идентификатора интересующей формы. Если в параметре передан верный идентификатор - метод должен отобразить окно с формой в диалоговом режиме (с возвратом управления только после ее закрытия). Если указан неверный параметр - должен сразу вернуть управление.

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

Может быть вызвана только в момент создания сценария. Реализация метода plugin-программы для отображения диалоговых plugin-форм c CONTROLTYPE = FORM (оконные) может совпадать с реализацией метода PrepareShow. Для отображения же plugin-форм с CONTROLTYPE = CONTROL (встраиваемые контролы) реализация должна предусматривать создание и размещение такой формы на внутреннем окне и вывод его на экран командой ShowDialog().

Пример передаваемого параметра:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="design" count="1">

  <property_set name="showformdesign">

    <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />

    <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />

  </property_set>

</data>

</oktellxmlmapper>

В качестве возвращаемого значения после закрытия формы должно вернуться описание результата. В случае если результат (свойство property_simple с ключом resultcode) не возвращает {"0", "success"}, текст результата из свойства property_cdata c ключом resultdescription будет отображен во всплывающем уведомлении.

string PrepareShow ( string xml )

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

Метод осуществляет создание, подготовку и отображение окна с формой в диалоговом режиме (с возвратом управления только после ее закрытия). Вызывается только в режиме операторских диалогов (module = "dialog") для оконных форм (controltype = "form").

Передаваемый параметр.

В качестве параметра - строка с XML содержимым. В нем в нескольких разделах перечислены

· Блок common. Общие данные по задаче, сценарию, абоненту, оператору, текущему комментарию, Guid идентификаторы plugin-программы и plugin-формы. Имеет жесткую структуру содержимого. Свойство idshow задает уникальный код экземпляра отображения - по нему будет запрашиваться закрытие и возврат значений.
· Блок input. Значения для входных параметров в установленном формате. Структура содержимого состоит из наборов, описывающих входные параметры. Их количество и формат определяются на основе данных,
· Блок fillinfo. Информация о наполнении (этапе). При переводе формы от одного оператора к другому у первого окно с формой закрывается, возвращая строку (любого формата) с неким содержимым. Это содержимое будет передано в управляющий объект plugin-программы в клиентском приложении второго оператора как часть структуры в параметре данного метода PrepareShow. См. также описание метода GetCurrentFillInfo. Блок может отсутствовать.

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

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="prepareparams" count="3">

<!-- ###################################################### -->

<!--        Раздел COMMON с общими параметрами              -->

<!-- ###################################################### -->

  <property_set name="сommon">

    <property_cdata key="idplugin"><![CDATA[b3daa197-f539-22f1-bc5a-8442fa9334ec]]></property_cdata>

    <property_cdata key="idform"><![CDATA[a69f5237-77ef-47fd-97d7-64e0da1c0457]]></property_cdata>

    <property_cdata key="iduser"><![CDATA[da803f01-ea77-40fa-bc9d-e2efb36fd5a8]]></property_cdata>

    <property_simple key="allowstop" value="1" />

    <property_simple key="showontop" value="1" />

    <property_cdata key="comment"><![CDATA[Тело комментария]]></property_cdata>

    <property_cdata key="taskname"><![CDATA[Обработка входящих]]></property_cdata>

    <property_simple key="idshow" value="8bc38a2a-5faa-4c75-864e-2f4e6723f1fd" />

    <property_collection count="2">

      <property_set name="clientinfo">

        <property_collection name="fields" count="3">

          <property_set id="0" name="field">

            <property_cdata key="fieldname"><![CDATA[Название]]></property_cdata>

            <property_cdata key="fieldvalue"><![CDATA[ООО "Гульчатай"]]></property_cdata>

          </property_set>

          <property_set id="1" name="field">

            <property_cdata key="fieldname"><![CDATA[Телефон]]></property_cdata>

            <property_simple key="fieldvalue" value="3214567" />

          </property_set>

          <property_set id="3" name="field">

            <property_cdata key="fieldname"><![CDATA[Контактное лицо]]></property_cdata>

            <property_cdata key="fieldvalue"><![CDATA[Веселовский Пал Виталич]]></property_cdata>

          </property_set>

        </property_collection>

      </property_set>

    </property_collection>

  </property_set>

<!-- ###################################################### -->

<!--        Раздел INPUT с заказанными параметрами          -->

<!-- ###################################################### -->

  <property_set name="input">

    <property_collection count="6">

      <property_set name="parameter" id="clientid">

        <property_simple key="paramkey" value="clientid" />

        <property_simple key="paramtype" value="1" />

        <property_simple key="paramextra" value="500" />

        <property_simple key="paramvalue" value="822" />

      </property_set>

      <property_set name="parameter" id="operator">

        <property_simple key="paramkey" value="operator" />

        <property_simple key="paramtype" value="1" />

        <property_simple key="paramextra" value="" />

        <property_cdata key="paramvalue"><![CDATA[Иванов Анатолий]]></property_cdata>

      </property_set>

      <property_set name="parameter" id="categories">

        <property_simple key="paramkey" value="categories" />

        <property_simple key="paramtype" value="7" />

        <property_simple key="paramextra" value="" />

        <property_simple key="paramvalue" value="0" />

      </property_set>

      <property_set name="parameter" id="queuetime">

        <property_simple key="paramkey" value="queuetime" />

        <property_simple key="paramtype" value="4" />

        <property_simple key="paramextra" value="" />

        <property_simple key="paramvalue" value="1,4142135623731" />

      </property_set>

.....................................................................................

Табличный параметр.

Имеет большой достаточно объем описательного текста даже при небольшом объеме данных

Его формат будет описан отдельно в пункте OnQuery

.....................................................................................

      <property_set name="parameter" id="products">

        <property_simple key="paramkey" value="products" />

        <property_simple key="paramtype" value="5" />

        <property_simple key="paramextra" value="" />

        <property_collection name="table" count="2">

          <property_set name="tableheader">

            <property_collection name="columns" count="3">

              <property_set name="columninfo" id="0">

                <property_simple key="index" value="0" />

                <property_simple key="name" value="id" />

                <property_simple key="typename" value="Int32" />

                <property_cdata key="typefullname"><![CDATA[System.Int32]]></property_cdata>

              </property_set>

              <property_set name="columninfo" id="1">

                <property_simple key="index" value="1" />

                <property_simple key="name" value="name" />

                <property_simple key="typename" value="String" />

                <property_cdata key="typefullname"><![CDATA[System.String]]></property_cdata>

              </property_set>

              <property_set name="columninfo" id="2">

                <property_simple key="index" value="2" />

                <property_simple key="name" value="st" />

                <property_simple key="typename" value="Boolean" />

                <property_cdata key="typefullname"><![CDATA[System.Boolean]]></property_cdata>

              </property_set>

            </property_collection>

          </property_set>

          <property_set name="tabledata">

            <property_collection name="rows" count="2">

              <property_set name="row" id="0">

                <property_collection name="cells" count="3">

                  <property_set name="cell" id="0">

                    <property_simple key="cellvalue" value="1" />

                  </property_set>

                  <property_set name="cell" id="1">

                    <property_simple key="cellvalue" value="qwer" />

                  </property_set>

                  <property_set name="cell" id="2">

                    <property_simple key="cellvalue" value="1" />

                  </property_set>

                </property_collection>

              </property_set>

              <property_set name="row" id="1">

                <property_collection name="cells" count="3">

                  <property_set name="cell" id="0">

                    <property_simple key="cellvalue" value="2" />

                  </property_set>

                  <property_set name="cell" id="1">

                    <property_simple key="cellvalue" value="wert" />

                  </property_set>

                  <property_set name="cell" id="2">

                    <property_simple key="cellvalue" value="1" />

                  </property_set>

                </property_collection>

              </property_set>

            </property_collection>

          </property_set>

        </property_collection>

      </property_set>

.....................................................................................

    </property_collection>

  </property_set>

<!-- ###################################################### -->

<!--   Раздел FILLINFO с информацией об этапе/заполнении    -->

<!-- ###################################################### -->

  <property_set name="fillinfo">

    <property_cdata key="fillinfo"><![CDATA[произвольная строка в любом формате от XML до B64]]></property_cdata>

  </property_set>

</data>

</oktellxmlmapper>

Возвращаемое значение.

В возвращаемой строке с XML содержимым должна присутствовать структура со значениями в двух разделах:

· Блок common. Новое значение комментария (передаваемого из формы в форму и от оператора к оператору), а также значение результата выполнения. По аналогии со стандартом операторского диалогового окна допускается два вида результатов: переход по кнопке Далее к следующему компоненту сценария с сохранением выходных значений в переменных сценария, а также остановка сценария кнопкой Стоп без сохранения выходных значений формы в переменных.
· Блок output. Набор, описывающий значения выходных параметров. Они будут применены в обработчике сценариев на сервере для сохранения в соответствующих переменных, указанных при настройке компонента «Plugin-форма».

В приведенном примере возвращаемого значения отмеченные зеленым цветом комментарии разделяют описанные зоны.

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="result" count="2">

<!-- ###################################################### -->

<!--   Раздел COMMON с общеий информацией о результате      -->

<!-- ###################################################### -->

  <property_set name="common">

    <property_cdata key="comment"><![CDATA[теперь вот такой комментарий]]></property_cdata>

    <property_simple key="result" value="next" />

  </property_set>

<!-- ###################################################### -->

<!--   Раздел OUTPUT со значениями выходных параметров      -->

<!-- ###################################################### -->

  <property_set name="output">

    <property_collection count="3">

      <property_set name="parameter" id="selectedproduct">

        <property_simple key="paramkey" value="selectedproduct" />

        <property_simple key="paramtype" value="2" name="int" />

        <property_simple key="paramvalue" value="12345555" />

      </property_set>

      <property_set name="parameter" id="info">

        <property_simple key="paramkey" value="info" />

        <property_simple key="paramtype" value="4" name="variable" />

        <property_cdata key="paramvalue"><![CDATA[выходное значение!!!]]></property_cdata>

      </property_set>

      <property_set name="parameter" id="dt">

        <property_simple key="paramkey" value="dt" />

        <property_simple key="paramtype" value="3" name="datetime" />

        <property_cdata key="datetimeformat"><![CDATA[dd.MM.yyyy HH:mm:ss]]></property_cdata>

        <property_cdata key="paramvalue"><![CDATA[01.12.2008 7:43:10]]></property_cdata>

      </property_set>

    </property_collection>

  </property_set>

</data>

</oktellxmlmapper>

string GetCurrentFillInfo ( string xml )

Вызывается для определения текущего наполнения формы (этапа) и последующего перевода формы на другого оператора в том виде, в котором она находится у текущего оператора.

Строковый параметр в XML структуре определяет код интересующей формы (хотя диалоговый режим поддерживает отображение только одной операторской диалоговой формы единовременно).

Возвращаемое значение может иметь любой формат и будет без разбора передано как часть структуры входного параметра (блок fillinfo) в метод PrepareShow или CreateControl на компьютере оператора, принимающего переведенный вызов.

Пример передаваемого параметра:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="close" count="1">

  <property_set name="forminfo">

    <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />

    <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />

    <property_simple key="idshow" value="e161da32-c52a-5515-e692-34bb1236a62d" />

  </property_set>

</data>

</oktellxmlmapper>

Пример возвращаемого значения:

произвольная строка в любом формате от XML до B64

string StopShow ( string xml )

Вызывается для принудительного закрытия диалоговой формы с CONTROLTYPE = FORM (оконные). Это может происходить в случае перевода звонка и соответствено формы на другого оператора (предварительно вызывается GetCurrentFillInfo) или в случае принудительного завершения диалогового сценария (по настройкам системы).

Строковый параметр в XML структуре определяет код интересующей формы (хотя диалоговый режим поддерживает отображение только одной операторской диалоговой формы единовременно).

Возвращается структура, содержащая значение комментария.

Пример передаваемого параметра:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="close" count="1">

  <property_set name="forminfo">

    <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />

    <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />

    <property_simple key="idshow" value="e161da32-c52a-5515-e692-34bb1236a62d" />

  </property_set>

</data>

</oktellxmlmapper>

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="result" count="1">

  <property_set name="common">

    <property_cdata key="comment"><![CDATA[Новое значение комментария]]></property_cdata>

  </property_set>

</data>

</oktellxmlmapper>

string GetControlResult ( string xml )

Вызывается для получения XML структуры со значениями выходных переменных для форм с CONTROLTYPE = CONTROL (контрольные). Поскольку отображение таких форм производится приложением Oktell (в отличие от оконных форм plugin-программы, для которых вызывается метод PrepareShow, осуществляющий подготовку, отображение и возврат управления вместе с описываемой структурой значений выходных параметров в контексте самой plugin-программы).

Строковый параметр в XML структуре определяет код интересующей формы (хотя диалоговый режим поддерживает отображение только одной операторской диалоговой формы единовременно).

Возвращаемое значение - XML структура установленного образца с содержимым, соответствующим значениям выходных параметров plugin-формы, структура и состав полностью аналогичны соответствующему возвращаемому значению метода PrepareShow.

Пример передаваемого параметра:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="controlresult" count="1">

  <property_set name="getresult">

    <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />

    <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />

    <property_simple key="idshow" value="a26a4540-6bee-4986-8098-adf340d3faa1" />

  </property_set>

</data>

</oktellxmlmapper>

Общие методы для обоих режимов использования

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

System.Windows.Forms.Control CreateControl ( string xml )

Используется и в режиме диалога, и в режиме подключения внешних модулей (CRM).

В режиме диалога вызывается для создания и подготовки формы с CONTROLTYPE = CONTROL (контрольные).

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

Возвращает созданный экземпляр контрола, который затем размещается в стандартном операторском диалоговом окне Oktell.

В режиме модулей CRM параметр имеет один и тот же вид: в содержимом XML структуры передаются идентификаторы plugin-программы, plugin-формы, экземпляра plugin-формы, а также информация о пользователе, рабочем месте, и т.д. Какие из переданных параметров использовать - дело управляющего объекта.

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

ВНИМАНИЕ! Окно представляет собой .NET форму (System.Windows.Forms.Form), которая в классовой структуре FrameWork является потомком System.Windows.Forms.Control.

Значение передаваемого параметра при использовании в режиме диалога полностью совпадает с параметром функции PrepareShow.

Пример параметра при создании для подключения среди внешних модулей (CRM):

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="info" count="3">

  <property_set name="user">

    <property_simple key="id" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8" />

    <property_cdata key="name"><![CDATA[Иванов Анатолий]]></property_cdata>

    <property_simple key="login" value="Ivanov" />

    <property_simple key="password" value="si4255" />

    <property_simple key="isoperator" value="1" />

    <property_simple key="issupervisor" value="1" />

    <property_simple key="isadmin" value="0" />

    <property_simple key="departmentid" value="c4e3b424-3048-4cce-a2e4-033c532a7d99" />

    <property_cdata key="departmentname"><![CDATA[Маркетинг]]></property_cdata>

  </property_set>

  <property_set name="workplace">

    <property_simple key="id" value="de609bc7-6d3b-4daf-a418-a1d0648d7784" />

    <property_cdata key="name"><![CDATA[Marketing1]]></property_cdata>

    <property_simple key="hasphone" value="1" />

  </property_set>

  <property_set name="link">

    <property_simple key="idshow" value="2e2d8ff0-de47-415f-ab68-9bddcd09952b" />

    <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />

    <property_simple key="idform" value="03e57976-b970-45ff-aec2-fa95ef274bd7" />

    <property_cdata key="linktext"><![CDATA[Форма 3 экз 1]]></property_cdata>

    <property_cdata key="headertext"><![CDATA[Демка, Форма 3 экз 1]]></property_cdata>

    <property_cdata key="description"><![CDATA[Описание пункта меню, задаваемое администратором]]></property_cdata>

    <property_cdata key="address"><![CDATA[Демонстрационный плагин / Модуль 3]]></property_cdata>

  </property_set>

</data>

</oktellxmlmapper>

Сервисное взаимодействие

Методы и события данного раздела служат для осуществления плотного взаимодействия plugin-программы и клиентского приложения Oktell. XML-содержимое описывает не только параметры, но и само действие (действия в общем случае). Не изменяя интерфейса подключения plugin-программ при помощи этих методов будут расширяться возможности взаимодействия, добавляться новые сервисы в клиентское приложение Oktell для использования в plugin-программах.

event PluginQueryInvoker OnQuery

Событие управляющего объекта, обрабатываемое в клиентском приложении Oktell. Служит для выполнения сервисных специальных запросов в клиентском приложении Oktell по инициативе plugin-программы или какой либо из ее plugin-форм. Результат выполнения попадает в управляющий объект как возвращаемое значение метода-обработчика. Параметр и возвращаемое значение представляют собой строки с XML-содержимым. Некоторые запросы должны обязательно содержать указание идентификатора plugin-формы и ее экземпляра, переданные через параметр метода CreateControl в момент создания.

Например могут быть осуществлены запросы в БД с возвратом некоторого набора данных, команды «Позвонить», «Переключить». В режиме модулей CRM команда на отображение специального текста в заголовке модуля, команда на отображение или смену вкладок на панели заголовка.

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

Описание структуры параметров обширно и приведено в отдельной статье «Сервисное взаимодействие».

string DoQuery ( string xml )

Событие приложения Oktell, обрабатываемое в управляющем объекте plugin-программы. Служит для выполнения сервисных специальных запросов в plugin-программе. Какие из них использовать и использовать ли вообще - дело управляющего объекта. Параметр и возвращаемое значение представляют собой строки с XML-содержимым.

Например в управляющий объект передаются события о смене активной вкладки в заголовке (сами вкладки появляются в приложении Oktell по событию OnQuery управляющего объекта). В управляющий объект также попадают события об отображении или скрытия той или иной формы, так как может потребоваться обновление данных, инициирование или остановка каких-либо таймеров и т.д.

Описание структуры параметров обширно и приведено в отдельной статье «Сервисное взаимодействие».


Сервисное взаимодействие

Методы и события данного раздела служат для осуществления плотного взаимодействия plugin-программы и клиентского приложения Oktell. XML-содержимое описывает не только параметры, но и само действие (действия в общем случае). Не изменяя интерфейса подключения plugin-программ при помощи этих методов будут расширяться возможности взаимодействия, добавляться новые сервисы в клиентское приложение Oktell для использования в plugin-программах.

· Событие «OnQuery»
· Параметр
· Возвращаемое значение
· Допустимые команды
· db
· dbdataset
· callnumber
· switchnumber
· callabort
· log
· notify
· tabs
· tabindex
· headertext
· headercolor
· faxsend
· faxabort
· downloadrecordbyid
· downloadrecordsbychain
· uploadfiletoserver
· downloadfilefromserver
· deletefilefromserver
· showdirectoryonserver
· sethandleevent
· svcscriptstart
· headsetcommand
· headsetcheckstate
· getallusersfullinfo
· getkeyid
· getqueueitems

· Метод «DoQuery»
· Параметр
· Возвращаемое значение
· Допустимые команды
· tabchange
· formshow
· formhide
· phoneevent
· pluginloaded

Событие OnQuery

Общее описание метода приведено в статье «Базовые элементы интерфейса. OnQuery». В текущем разделе приводится формат параметров при обмене сообщениями в контексте метода.

Параметр (запрос от plugin-программы к приложению Oktell)

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

Для простоты и однотипности организации кода приложение Oktell всегда возвращает ответ (в простейшем случае - единственное свойство resultcode).

В общем виде запрос состоит из нескольких независимых подзапросов, исполняемых поочередно. Каждый запрос в теле XML-структуры установленного образца имеет вид элемента property_set первого уровня (вложенного в основную коллекцию). Тип запроса определяется строковым кодом (значением атрибута name) элемента property_set. Все необходимые для исполнения запроса параметры составляют свойства элемента. В отдельных случаях элемент может иметь сложную структуру, содержать коллекцию вложенных элементов.

Структура параметра-запроса:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="query" count="...">

  <property_set name="..." id="...">

    ...

  </property_set>

...........................................

...........................................

...........................................

  <property_set name="..." id="...">

    ...

  </property_set>

</data>

</oktellxmlmapper>

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

Возвращаемое значение (ответ приложения Oktell на запрос plugin-программы)

Структура ответа:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="queryresult" count="...">

  <property_set name="..." id="...">

    <property_simple key="resultcode" value="..." name="..." />

    <property_cdata key="resultdescription"><![CDATA[...]]></property_cdata>

...

  </property_set>

...........................................

...........................................

...........................................

  <property_set name="..." id="...">

    <property_simple key="resultcode" value="..." name="..." />

    <property_cdata key="resultdescription"><![CDATA[...]]></property_cdata>

    ...

  </property_set>

</data>

</oktellxmlmapper>

Каждый элемент property_set в базовой коллекции соответствует элементу в запросе. Может быть выполнена часть запросов, а некоторые (например из-за содержащихся в параметрах запроса ошибок) будут иметь неудачный код возврата.

В частном наиболее употребимом случае запрос состоит из одной команды (одного блока property_set). Соответствующий ему ответ также состоит из одного блока.

Существует единственный случай, когда ответ не имеет сопоставления с запросом - если строка XML имеет некорректный вид или нестандартный для интерфейса формат. В этом случае ответ будет возвращен в виде:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="queryresult" count="1">

  <property_set name="commonresult">

    <property_simple key="resultcode" value="105" name="ErrorInputXml" />

    <property_cdata key="resultdescription"><![CDATA[Неверный формат XML-запроса]]></property_cdata>

  </property_set>

</data>

</oktellxmlmapper>

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

private enum EQueryResult

{

Success = 100, //Запрос успешно выполнен
Exception = 101, //При выполнении запроса возникло исключение (текст в блоке resultdescription)
UnknownCommand = 102, //Неизвестный тип запроса
IncorrectParameter = 103, //Не задан или некорректно задан необходимый параметр
Error = 104, //Общая ошибка
ErrorInputXml = 105, //Ошибка при разборе XML-содержимого запроса

}

Допустимые типы запросов

db

dbdataset

callnumber

switchnumber

callabort

log

notify

tabs

tabindex

headertext

headercolor

faxsend

faxabort

downloadrecordbyid

downloadrecordsbychain

uploadfiletoserver

downloadfilefromserver

deletefilefromserver

showdirectoryonserver

sethandleevent

svcscriptstart

headsetcommand

headsetcheckstate

getallusersfullinfo

getkeyid

getqueueitems

· db

Осуществляет запрос к БД средствами Oktell.

В теле элемента property_set должно быть указано свойство sqltext. Текст запроса должен иметь полностью сформированный вид и будет передан без дополнительных параметров на сервер, а затем в БД. Запрос должен представлять из себя один batch-блок, и может иметь любую сложность (содержать переменные, курсоры, вести обработку в цикле и т.д.)

Возвращаемое значение (одиночный набор) будет преобразовано в XML-структуру и возвращено в plugin-программу в виде ответа (в соответствующем разделе полного запроса).

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

Структура запроса:

<property_set name="db" id="...">

<property_cdata key="sqltext"><![CDATA[...]]></property_cdata>

</property_set>

Структура ответа в случае успешного выполнения:

<property_set name="db" id="...">

<!--##### Общие свойства #####-->

<property_simple key="resultcode" value="100" name="Success" />

<property_cdata key="resultdescription"><![CDATA[Success]]></property_cdata>

<property_simple key="sqlresultcode" value="0" name="qrSuccess" />

<property_cdata key="sqlresultdescription"><![CDATA[qrSuccess]]></property_cdata>

<!--##### Возвращаемый набор #####-->

<property_collection name="table" count="...">

<!--##### Описание столбцов #####-->

<property_set name="tableheader">

<property_collection name="columns" count="...">

<!--##### Один столбец: индекс, название, тип и полное название типа #####-->

<property_set name="columninfo" id="0">

<property_simple key="index" value="0" />

<property_simple key="name" value="Id" />

<property_simple key="typename" value="Guid" />

<property_cdata key="typefullname"><![CDATA[System.Guid]]></property_cdata>

</property_set>

<property_set name="columninfo" id="2">

<property_simple key="index" value="1" />

<property_simple key="name" value="Name" />

<property_simple key="typename" value="String" />

<property_cdata key="typefullname"><![CDATA[System.String]]></property_cdata>

</property_set>

...............

</property_collection>

</property_set>

<!--##### Раздел с данными #####-->

<property_set name="tabledata">

<property_collection name="rows" count="2">

<!--##### Одна строка: индекс строки, коллекция ячеек (значений) #####-->

<property_set name="row" id="0">

<!--##### Все ячейки #####-->

<property_collection name="cells" count="2">

<!--##### Одна ячейка: индекс столбца, значение #####-->

<property_set name="cell" id="0">

<property_simple key="cellvalue" value="17e640e1-1d55-4e45-a193-0469cbcd2dce" />

</property_set>

<property_set name="cell" id="1">

<property_cdata key="cellvalue"><![CDATA[Максим]]></property_cdata>

</property_set>

</property_collection>

</property_set>

<property_set name="row" id="1">

<property_collection name="cells" count="2">

<property_set name="cell" id="0">

<property_simple key="cellvalue" value="309a147f-6248-4fbd-8b28-09b679c8297a" />

</property_set>

<property_set name="cell" id="1">

<property_simple key="cellvalue" value="z08" />

</property_set>

</property_collection>

</property_set>

</property_collection>

</property_set>

</property_collection>

</property_set>

· dbdataset

Осуществляет запрос к БД средствами Oktell. В отличие от метода «db» структуру, получаемую на сервере, загружает в DataSet и формирует на ее базе XML строку, преобразованную в Base64.

Для обратного преобразования необходимо полученную из поля CDATA строку подвергнуть обработке следующим кодом (C#):

DataSet ds = new DataSet();

MemoryStream ms = new MemoryStream ( Convert.FromBase64String ( dsxml ) );

ds.ReadXml ( ms );

Структура запроса:

<property_set name="dbdataset" id="...">

<property_cdata key="sqltext"><![CDATA[...]]></property_cdata>

</property_set>

Структура ответа в случае успешного выполнения:

<property_set name="db" id="...">

<!--##### Общие свойства #####-->

<property_simple key="resultcode" value="100" name="Success" />

<property_cdata key="resultdescription"><![CDATA[Success]]></property_cdata>

<property_simple key="sqlresultcode" value="0" name="qrSuccess" />

<property_cdata key="sqlresultdescription"><![CDATA[qrSuccess]]></property_cdata>

<!--##### Возвращаемый набор #####-->

<property_collection name="dataset" count="1">

<!--##### Описание столбцов #####-->

<property_set name="datasetxmlb64">

 <property_cdata key="xmlb64"><![CDATA[.....Base64......]]></property_cdata>

</property_set>

</property_collection>

</property_set>

· callnumber

Осуществляет запрос к серверу на совершение вызова средствами менеджера автодозвона.

Структура запроса:

<property_set name="callnumber" id="...">

<property_simple key="number" value="..." />

<property_simple key="direction" value="..." />

</property_set>

Свойство number содержит номер, вызов которого необходимо осуществить. Свойство direction может принимать значения "pbx" или "city" и определяет направление вызова - во внутренний номерной план или во внешние линии соответственно. Если свойство не будет указано или будет указано неверно, то вызов будет осуществляться во внутренний номерной план, если в нем зарегистрирован указанный номер, и на внешние линии иначе.

Структура ответа:

<property_set name="callnumber" id="...">

<property_simple key="resultcode" value="100" name="Success" />

<property_simple key="resultdescription" value="Success" />

<property_simple key="acmresultcode" value="0" name="cntStartedSuccessfully" />

</property_set>

Свойство acmresultcode может принимать значения из перечисления:

public enum EACMAnswer

{

cntStartedSuccessfully  = 0, //Звонок успешно взят в реализацию
cntUserNotReady = 1, //У осуществляющего вызов пользователя не найдены линии, готовые линии, или состояние кривое
cntBusy = 2, //При звонке на внутренний номер - признак занятости. В очереди и сам повисеть может (в дальнейшем реализуем как раз ожидание в очереди...)
cntExtLineNotFound = 3, //Не найдены готовые внешние линии после длительного ожидания и нескольких попыток
cntError = 4, //Прочие ошибки, исключения
cntControlNotReady = 5, //Режим не реализован
cntNumberNotFound = 6, //Внутренний номер не найден (если сервер самостоятельно определяет направление звонка, то это не задействовано)

}

· switchnumber

Осуществляет запрос к серверу на совершение переключения (flash-буферизации текущего абонента и последующего вызова указанного номера).

Структура запроса:

<property_set name="switchnumber" id="...">

<property_simple key="number" value="..." />

<property_simple key="direction" value="..." />

</property_set>

Свойство number содержит номер, вызов которого необходимо осуществить. Свойство direction может принимать значения "pbx" или "city" и определяет направление вызова - во внутренний номерной план или во внешние линии соответственно. Если свойство не будет указано или будет указано неверно, то вызов будет осуществляться во внутренний номерной план, если в нем зарегистрирован указанный номер, и на внешние линии иначе.

Структура ответа совпадает с ответом команды callnumber.

· callabort

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

Структура запроса:

<property_set name="callabort" id="..." />

Ответ содержит только стандартные поля resultcode и resultdescription.

· log

Осуществляет вывод текстовой информации в стандартный лог-журнал Plugin клиентского приложения Oktell.

Структура запроса:

<property_set name="log" id="...">

<property_cdata key="logstring"><![CDATA[...]]></property_cdata>

</property_set>

Ответ содержит только стандартные поля resultcode и resultdescription.

· notify

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

Структура запроса:

<property_set name="notify" id="...">

<property_simple key="type" value="..." /> ("info", "warn", "err", "color")

<property_simple key="autohide" value="..." /> ("1", "0")

<property_simple key="savedb" value="..." /> ("1", "0")

<property_simple key="color" value="..." /> ("White", "LightRed", "Green", "Azure", "DarkKhaki", ...)

<property_cdata key="sender"><![CDATA[...]]></property_cdata>

<property_cdata key="text"><![CDATA[...]]></property_cdata>

</property_set>

Варианты значений для свойства type: info, warn, err, color.

Варианты значений для свойства autohide: 0, 1.

Варианты значений для свойства savedb: 0, 1.

Варианты значений для свойства color: White, LightRed, Green, Azure, DarkKhaki, .... Названия всех цветов FrameWork.

Ответ содержит только стандартные поля resultcode и resultdescription.

· tabs

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

Для корректного применения в структуре параметров команды необходимо указание формы (idform) и уникального идентификатора, передаваемого из приложения Oktell при ее создании (idshow).

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

Структура запроса:

<property_set name="tabs" id="...">

<property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />

<property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />

<property_simple key="idshow" value="f489439b-12f3-4425-91b5-d03e89101665" />

<property_simple key="activeindex" value="2" />

<property_collection name="tabs" count="...">

<property_set name="tabinfo">

<property_simple key="index" value="1" />

<property_cdata key="name"><![CDATA[...]]></property_cdata>

</property_set>

<property_set name="tabinfo">

<property_simple key="index" value="2" />

<property_cdata key="name"><![CDATA[...]]></property_cdata>

</property_set>

...

</property_collection>

</property_set>

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

Коллекция описателей вкладок - элементы property_set, вложенные в базовый элемент команды - содержит описание каждой вкладки набором {index, name}, который определяет код вкладки при обмене событийными сообщениями по части вкладок между приложением и plugin-программой, а также отображаемое в панели заголовка название.

Ответ содержит только стандартные поля resultcode и resultdescription.

· tabindex

В случае использования формы в режиме отображения среди внешних модулей осуществляет смену активной вкладки по инициативе plugin-программы.

Для корректного применения в структуре параметров команды необходимо указание формы (idform) и уникального идентификатора, передаваемого из приложения Oktell при ее создании (idshow).

Структура запроса:

<property_set name="tabs" id="...">

<property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />

<property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />

<property_simple key="idshow" value="f489439b-12f3-4425-91b5-d03e89101665" />

<property_simple key="activeindex" value="..." />

</property_set>

Свойство activeindex устанавливает индекс вкладки (согласно индексам, определенных в коллекции-перечислении), которая должна стать активной. Индекс вкладки определяется при генерации события на отображение вкладок tabs.

Ответ содержит только стандартные поля resultcode и resultdescription.

· headertext

В случае использования формы в режиме отображения среди внешних модулей осуществляет смену текста заголовка модуля в главном окне приложения Oktell по инициативе plugin-программы.

Для корректного применения в структуре параметров команды необходимо указание формы (idform) и уникального идентификатора, передаваемого из приложения Oktell при ее создании (idshow). Свойство text определяет новое значение заголовка.

Структура запроса:

<property_set name="headertext" id="...">

<property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />

<property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />

<property_simple key="idshow" value="f489439b-12f3-4425-91b5-d03e89101665" />

<property_cdata key="text"><![CDATA[...]]></property_cdata>

</property_set>

Ответ содержит только стандартные поля resultcode и resultdescription.

· headercolor

В случае использования формы в режиме отображения среди внешних модулей осуществляет смену цвета заголовка модуля в главном окне приложения Oktell по инициативе plugin-программы.

Для корректного применения в структуре параметров команды необходимо указание формы (idform) и уникального идентификатора, передаваемого из приложения Oktell при ее создании (idshow). Свойство color определяет новое значение цвета в числовом формате (int argb). В приведенном примере указан десятичный эквивалент числа 0x00FF0000 - красный цвет.

Структура запроса:

<property_set name="headertext" id="...">

<property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />

<property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />

<property_simple key="idshow" value="f489439b-12f3-4425-91b5-d03e89101665" />

<property_cdata key="color" value="16711680"/>

</property_set>

Ответ содержит только стандартные поля resultcode и resultdescription.

· faxsend

В момент активной коммутации выполняет команду на переключение в режим отправки факса через оппозитный канал (функция аналогичная команде "Отправка факса" модуля "Телефон" клиентского приложения Oktell). Функции по работе с факсом приложения и plugin-программы взаимозаменяемы и взаимодополняемы.

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

Структура запроса:

<property_set name="faxsend" id="...">

<property_cdata key="filepath"><![CDATA[...]]></property_cdata>

</property_set>

Ответ содержит стандартные поля resultcode и resultdescription, а также поле faxsendresult с результатом выполнения команды на отправку. В нем "0" указывает на обрыв выполнения команды из-за несоответствия условий, например, если на оппозитном канале отсутствует функция факса.

· faxabort

В момент активного сеанса передачи факса через оппозитный канал (ручной режим передачи) выполняет обрыв и переход в коммутацию с оппозитным каналом (функция аналогичная команде "Отмена факса" модуля "Телефон" клиентского приложения Oktell). Функции по работе с факсом приложения и plugin-программы взаимозаменяемы и взаимодополняемы.

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

Структура запроса:

<property_set name="faxabort" id="...">

</property_set>

Ответ содержит стандартные поля resultcode и resultdescription, а также поле faxabortresult с результатом выполнения команды на обрыв факса. В нем "0" указывает на то, что факс-передача не осуществлялась, и команда на обрыв была пропущена.

· downloadrecordbyid

Осуществляет запрос к серверу на закачку файла записи разговора (коммутации) из хранилища записей на сервере на клиентский компьютер в указанное место. В случае, если на сервере файлы записи каналов одного разговора еще не микшированы, производится моментальное микширование и пересылка одного файла.

Свойство idconn определяет код (Guid) коммутации, запись которой требуется скачать, в формате "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX". Свойство filepath определяет полный путь на клиентском компьютере к итоговому файлу, куда будет сохранена запись.

Структура запроса:

<property_set name="downloadrecordbyid" id="...">

<property_cdata key="idconn"><![CDATA[...]]></property_cdata>

<property_cdata key="filepath"><![CDATA[...]]></property_cdata>

</property_set>

Ответ содержит стандартные поля resultcode и resultdescription, а также поле downloadresult с результатом выполнения команды на загрузку файлов. В нем "1" указывает на успешное завершение операции, "0" - файлы не найдены и не загружены.

· downloadrecordsbychain

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

Свойство idchain определяет код (Guid) цепочки, записи разговоров которой требуется скачать, в формате "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX". Свойство folderpath определяет полный путь на клиентском компьютере к каталогу, куда будут сохранены записи с исходными именами файлов.

Структура запроса:

<property_set name="downloadrecordbyid" id="...">

<property_cdata key="idchain"><![CDATA[...]]></property_cdata>

<property_cdata key="folderpath"><![CDATA[...]]></property_cdata>

</property_set>

Ответ содержит стандартные поля resultcode и resultdescription, а также поле downloadresult с результатом выполнения команды на загрузку файлов. В нем «1» указывает на успешное завершение операции, «0» - файлы не найдены и не загружены.

Поле downloadcount в ответе появляется в случае успешной загрузки хотя бы одного файла и содержит общее количество загруженных файлов. Также в ответе перечислены полные пути на клиентском компьютере ко всем загруженным файлам.

Структура ответа:

<property_set name="downloadrecordbyid" id="...">

<property_simple key="resultcode" value="100" name="Success" />

<property_simple key="resultdescription" value="Success" />

<property_simple key="downloadresult" value="1" name="success" />

<property_simple key="downloadcount" value="2" />

<property_collection name="filepaths" count="2">

<property_set id="0">

  <property_simple key="index" value="0" />

  <property_cdata key="filepath"><![CDATA[...]]></property_cdata>

</property_set>

<property_set id="1">

  <property_simple key="index" value="1" />

  <property_cdata key="filepath"><![CDATA[...]]></property_cdata>

</property_set>

................

</property_collection>

</property_set>

· uploadfiletoserver

Осуществляет запрос к серверу на закачку одного файла с клиента на сервер. Размещение осуществляется в указанном месте на сервере. Файл должен существовать в указанном месте клиентского компьютера.

Свойство localpath определяет абсолютный путь к файлу на клиентском компьютере. Свойство serverpath определяет путь на сервере, куда требуется загрузить файл. Может быть задан абсолютный путь или относительный (от каталога серверной службы) - в этом случае поле isrelative должно быть указано и иметь значение "1". Может быть указан полный путь к файлу (тогда исходное имя файла при сохранении теряется в пользу указанного), либо может быть указан путь к каталогу (тогда файл сохранится с исходным именем) - в этом случае поле isfolder должно быть указано и иметь значение "1".

Структура запроса:

<property_set name="uploadfiletoserver" id="...">

<property_cdata key="localpath"><![CDATA[...]]></property_cdata>

<property_cdata key="serverpath"><![CDATA[...]]></property_cdata>

<property_simple key="isrelative" value="0" />

<property_simple key="isfolder" value="0" />

</property_set>

Ответ содержит стандартные поля resultcode и resultdescription, а также поле serverfilepath - возвращает полный путь к загруженному файлу на сервере (может быть необходим plugin-программе в случае, если используется загрузка по относительному пути).

· downloadfilefromserver

Осуществляет запрос к серверу на скачивание одного файла с сервера на клиентский компьютер. Размещение осуществляется в указанном месте на локальной машине. Файл должен существовать в указанном месте серверного компьютера.

Свойство localpath определяет абсолютный путь к файлу на клиентском компьютере, куда следует разместить файл после загрузки с сервера. Свойство serverpath определяет путь на сервере, откуда требуется скачать файл. Может быть задан абсолютный путь или относительный (от каталога серверной службы) - в этом случае поле isrelative должно быть указано и иметь значение "1".

Структура запроса:

<property_set name="downloadfilefromserver" id="...">

<property_cdata key="localpath"><![CDATA[...]]></property_cdata>

<property_cdata key="serverpath"><![CDATA[...]]></property_cdata>

<property_simple key="isrelative" value="0" />

</property_set>

Ответ содержит стандартные поля resultcode и resultdescription, а также поле downloadresult - «1» в случае успешного закачивания файла, «0» в случае не обнаружения файла в указанном месте сервера.

· deletefilefromserver

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

Свойство serverpath определяет путь на сервере, откуда требуется скачать файл. Может быть задан абсолютный путь или относительный (от каталога серверной службы) - в этом случае поле isrelative должно быть указано и иметь значение "1".

Структура запроса:

<property_set name="deletefilefromserver" id="...">

<property_cdata key="serverpath"><![CDATA[...]]></property_cdata>

<property_simple key="isrelative" value="0" />

</property_set>

Ответ содержит стандартные поля resultcode и resultdescription, а также поле deleteresult - «1» в случае успешного удаления файла, «0» в случае не обнаружения файла в указанном месте сервера или запрета на удаление.

· showdirectoryonserver

Осуществляет запрос к серверу на получение структуры указанного каталога.

Свойство serverpath определяет путь на сервере к исследуемому каталогу, структуру которого требуется получить. Может быть задан абсолютный путь или относительный (от каталога серверной службы) - в этом случае поле isrelative должно быть указано и иметь значение "1". Установленные поля showfiles и showdirs определяют соответственно перечисление файлов и подкаталогов. Поле pattern определяет маску выборки элементов (например *.txt).

Структура запроса:

<property_set name="showdirectoryonserver" id="...">

<property_cdata key="serverpath"><![CDATA[...]]></property_cdata>

<property_simple key="isrelative" value="0" />

<property_simple key="showfiles" value="1" />

<property_simple key="showdirs" value="0" />

<property_cdata key="pattern"><![CDATA[...]]></property_cdata>

</property_set>

Ответ содержит стандартные поля resultcode и resultdescription, а также поле showdirectoryresult - «0» в случае отсутствия каталога по указанному пути, и «1» в случае успешного выполнения операции. Раздел consistence содержит перечисление обнаруженных элементов.

Структура ответа:

<property_set name="showdirectoryonserver" id="...">

<property_simple key="resultcode" value="100" name="Success" />

<property_simple key="resultdescription" value="Success" />

<property_simple key="showdirectoryresult" value="1" name="success" />

<property_collection name="consistence" count="2">

<property_set name="directories">

  <property_cdata key="dir" value="0"><![CDATA[Subdir1]]></property_cdata>

  <property_cdata key="dir" value="1"><![CDATA[Subdir2]]></property_cdata>

  <property_cdata key="dir" value="2"><![CDATA[Subdir3]]></property_cdata>

  <property_cdata key="dir" value="3"><![CDATA[Subdir4]]></property_cdata>

</property_set>

<property_set name="files">

  <property_cdata key="file" value="0"><![CDATA[1.txt]]></property_cdata>

</property_set>

................

</property_collection>

</property_set>

· sethandleevent

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

Сервер и клиентское приложение генерируют множество событий, не все из которых могут быть интересны plugin-программе (лишние события это всегда затрата лишних ресурсов и времени на пустую обработку). Соответственно события разбиты на группы, и плагины осуществляют таким образом подписку на группы. Строка-значение свойства eventtype определяет текстовый код направления подписки. Свойство handle со значением «1» подписывает указанный плагин на событийное направление, со значением «0» напротив отписывает. Для проведения подписки/отписки должен быть задан идентификатор плагин-программы.

Структура запроса:

<property_set name="sethandleevent" id="...">

<property_cdata key="idplugin"><![CDATA[...]]></property_cdata>

<property_simple key="handle" value="1" />

<property_simple key="eventtype" value="phoneevent" />

</property_set>

Ответ содержит стандартные поля resultcode и resultdescription.

События, генерируемые приложением, будут поступать после подписки на соответствующее направление в plugin-программу путем вызова метода DoQuery. В параметре будет указан тип и код направления, тип и код события, а также дополнительные параметры конкретного события. При этом событийные направления определяют допустимые типы запросов с кодами 203**.

Доступные направления:

· phoneevent - события аппаратного модуля и логики АТС по управлению каналом, связанным с рабочим местом, на котором исполняется plugin-программа.

· svcscriptstart

Осуществляет запрос к серверу на запуск служебного сценария по инициативе плагин-программы. Запуск может производиться в синхронном режиме с ожиданием исполнения и возвратом значения из служебной переменной сценария по завершению исполнения (в этом случае поток приложения блокируется до завершения или до таймаута). Также запуск может производиться в асинхронном режиме (без ожидания выполнения).

Свойство scriptname определяет имя сценария. Полный путь вычисляется на сервере, сценарий загружается из папки общих служебных сценариев. Свойство startparam устанавливает при необходимости начальный стартовый параметр, передаваемый в компонент «Старт» сценария. Свойство startmode определяет режим запуска служебного сценария: «1» - асинхронный (только запуск), «2» - синхронный с ожиданием завершения исполнения и возвратом значения из служебной переменной «Возвращаемое значение». По умолчанию при отсутствии параметра выставляется синхронный режим. В синхронном режиме может быть задано свойство timeout, определяющее в секундах максимальное время ожидания завершения работы сценария, по истечению которого сценарий продолжит выполнение, но управление вернется в плагин без ожидания возвращаемого значения.

Структура запроса:

<property_set name="svcscriptstart" id="...">

<property_cdata key="scriptname"><![CDATA[...]]></property_cdata>

<property_simple key="startparam" value="" />

<property_simple key="startmode" value="2" />

<property_simple key="timeout" value="1" />

</property_set>

Ответ содержит стандартные поля resultcode и resultdescription. Дополнительно возвращаются также несколько служебных значений. Поле started - «1» в случае успешного запуска сценария, «0» в случае, если сценарий не стартовал по какой-либо причине. Поле startresult - «0» в случае успешного исполнения команды, «10» в случае не обнаружения сценария, «11» в случае сбоя при запуске, «12» в случае таймаута ожидания в синхронном режиме. Поле returnvalue присутствует только в синхронном режиме и возвращает значение служебной переменной «Возвращаемое значение».

· headsetcommand

Отправляет команду локальному модулю HAL, управляющему локальным устройством типа гарнитуры. Допускаются команды DTMF, Поднять трубку, Положить трубку, Генерировать флэш, Проиграть звуковой файл установленного формата (Oktell сам использует только для тестов, но функция доступна). Может потребоваться для организации в plugin-программе модуля, аналогичного встроенному софт-телефону приложения Oktell.

Для устройств, не являющихся локально управляемыми гарнитурами, в общем случае метод бессмысленен. Однако его функционал незначительно расширен, так, например, вызов FLASH и DTMF достигают АТС в любом случае при наличии какого-либо устройства. Дополнительно, вызов HOOKDOWN для устройств, отличных от гарнитур, обрывает текущий сеанс коммутации, а также производит остановку сервиса автодозвона, если он был запущен.

Коды команд:

hookup = 0 //поднять трубку или ответить на вызов
hookdown = 1 //положить трубку или разорвать коммутацию
flash = 2 //генерировать flash
dtmf = 3 //отправить dtmf символы с канала на сервер
playfile = 4 //воспроизвести мелодию в канал
mute = 5 //включить/отключить исходящий звук

Свойство command определяет требуемую к исполнению команду. В качестве значения могут быть заданы числовые коды или имена. В случае сложных команд, требующих указания параметра, ожидается наличие свойства data, содержащего его значение (в случае команды dtmf в качестве параметра ожидается конкретный символ, в случае playfile - путь к файлу).

Структура запроса на примерах

1.

<property_set name="headsetcommand" id="...">

<property_simple key="command" value="2" />

</property_set>

2.

<property_set name="headsetcommand" id="...">

<property_simple key="command" value="3"/>

<!-- (генерируемый символ dtmf) -->

<property_simple key="data" value="*"/>

</property_set>

3.

<property_set name="headsetcommand" id="...">

<property_simple key="command" value="mute"/>

<!-- (0-включить звук, 1-отключить звук) -->

<property_simple key="data" value="1"/>

</property_set>

Ответ содержит стандартные поля resultcode и resultdescription. Дополнительно возвращается также поле commandresult, указывающее на результат исполнения.

· headsetcheckstate

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

Коды команд:

hookup = 1 //снята ли трубка
ringing = 2 //осуществляется ли вызов устройства (звонок)
connected = 3 //подключено/обнаружено ли устройство
registered = 4 //зарегистрирован ли канал на сервере
muted = 5 //отключен ли исходящий звук

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

Структура запроса на примерах:

<property_set name="headsetcheckstate" id="...">

<property_simple key="command" value="2" />

</property_set>

или

<property_set name="headsetcheckstate" id="...">

<property_simple key="command" value="ringing"/>

</property_set>

Ответ содержит стандартные поля resultcode и resultdescription. Дополнительно возвращается также поле commandresult, в котором содержится результат исполнения: «1» - состояние активно, «0» - состояние неактивно.

· getallusersfullinfo

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

Структура запроса:

<property_set name="getallusersfullinfo" id="...">

</property_set>

Ответ содержит стандартные поля resultcode и resultdescription. В коллекции ответа содержится список всех пользователей с перечнем свойств.

Структура ответа:

<property_set name="getallusersfullinfo" id="...">

<property_simple key="resultcode" value="100" name="Success" />

<property_cdata key="resultdescription"><![CDATA[Success]]></property_cdata>

<property_collection name="users" count="...">

<property_set name="user" id="da803f01-ea77-40fa-bc9d-e2efb36fd5a8">

<property_cdata key="id"><![CDATA[da803f01-ea77-40fa-bc9d-e2efb36fd5a8]]></property_cdata>

<property_cdata key="name"><![CDATA[Букашин Петр Александрович]]></property_cdata>

<property_simple key="isoperator" value="1" />

<property_cdata key="groupid"><![CDATA[f42c8dd4-6e6b-4033-9349-5d51971fb251]]></property_cdata>

<property_cdata key="groupname"><![CDATA[Техническое управление]]></property_cdata>

<property_simple key="userstate" value="1" name="usReady" />

<property_simple key="iscc" value="1" />

<property_simple key="islunch" value="0" />

<property_simple key="isredirect" value="0" />

<property_cdata key="lineid"><![CDATA[cf8330f4-a0bf-4779-9539-ab8ea6c49df7]]></property_cdata>

<property_simple key="linenum" value="16016" name="Success" />

<property_simple key="linetype" value="4" name="ltIntUSB" />

<property_simple key="linestate" value="4" name="lsReady" />

</property_set>

...

<property_set name="user" id="...">

...

</property_set>

</property_collection>

</property_set>

· getkeyid

Осуществляет запрос к серверу для определения номера текущего ключа защиты. Возвращает 9-значный номер или 0, если ключ не обнаружен или сбой при обращении к ключу.

Структура запроса:

<property_set name="getkeyid" id="...">

</property_set>

Ответ содержит стандартные поля resultcode и resultdescription. Также в структуре ответа содержится поле keyidresult, содержащее 9-значный номер текущего используемого ключа защиты.

Структура ответа:

<property_set name="getkeyid" id="...">

<property_simple key="resultcode" value="100" name="Success" />

<property_cdata key="resultdescription"><![CDATA[Success]]></property_cdata>

<property_simple key="keyid" value="720509402" />

</property_set>

· getqueueitems

Осуществляет запрос к серверу для получения текущего списка элементов в очереди ожидания.

Структура запроса:

<property_set name="getqueueitems" id="...">

</property_set>

Ответ содержит стандартные поля resultcode и resultdescription. Также в структуре ответа содержится структура currentqueue c информацией о всех элементах в очереди на момент запроса. Поля описания каждого элемента очереди аналогичны соответствующим значениям возвращаемого значения функции Queue_GetCurrentItems раздела «Oktell в других проектах. Методы для работы с АТС: очередь ожидания».

Структура ответа на примере:

<property_set name="getqueueitems">

<property_simple key="resultcode" value="100" name="Success" />

<property_cdata key="resultdescription"><![CDATA[Success]]></property_cdata>

<property_collection name="currentqueue" count="2">

  <property_set name="queueitem">

    <property_simple key="dateformat" value="dd.MM.yyyy HH:mm:ss" />

    <property_simple key="managedlineid" value="9fe668ff-0822-4b8d-aa0a-71fbbaad0c67" />

    <property_simple key="objecttype" value="0" name="qotQueueLogic" />

    <property_cdata key="username"><![CDATA[Замятин Олег Васильевич]]></property_cdata>

    <property_simple key="lenqueue" value="137000" />

    <property_simple key="srcelementid" value="a00a7a08-b3f7-44f3-8b2c-64ef11d4a2c5" />

    <property_simple key="queuesource" value="1" name="qsLineLogic" />

    <property_cdata key="department"><![CDATA[Руководство]]></property_cdata>

    <property_simple key="calledid" value="14" />

    <property_simple key="callerid" value="21" />

    <property_simple key="idobject" value="12345678-1234-1234-1234-12345678123a" />

    <property_simple key="userid" value="ba0a387e-815a-434d-8ace-1a1840916761" />

    <property_simple key="managedlinenum" value="1525" />

    <property_simple key="startqueuetime" value="02.11.2009 10:43:36" />

    <property_simple key="queuepriority" value="10" />

  </property_set>

  <property_set name="queueitem">

    <property_simple key="dateformat" value="dd.MM.yyyy HH:mm:ss" />

    <property_simple key="tasklistid" value="-1" />

    <property_simple key="idobject" value="12345678-1234-1234-1234-12345678123b" />

    <property_simple key="taskisoutput" value="0" />

    <property_simple key="managedlinenum" value="1001" />

    <property_simple key="userid" value="00000000-0000-0000-0000-000000000000" />

    <property_cdata key="taskname"><![CDATA[Прием входящих]]></property_cdata>

    <property_simple key="calledid" value="5109940" />

    <property_simple key="srcelementid" value="cf82a296-2b27-43c8-a607-1579c83d0b8f" />

    <property_simple key="username" value="" />

    <property_simple key="startqueuetime" value="02.11.2009 10:43:36" />

    <property_simple key="objecttype" value="0" name="qotQueueLogic" />

    <property_simple key="lenqueue" value="277000" />

    <property_simple key="callerid" value="89050213951" />

    <property_simple key="queuepriority" value="10" />

    <property_simple key="managedlineid" value="d2d2bd39-d5a3-4d83-b78f-d6ac25cb2733" />

    <property_simple key="department" value="" />

    <property_simple key="taskid" value="79f0627c-3372-474c-9d9a-8fc3627a3ed8" />

    <property_simple key="queuesource" value="5" name="qsIncomingTask" />

  </property_set>

</property_collection>

</property_set>

Список возможных сервисных команд будет пополняться. В случае, если вам необходимо получить дополнительный функционал, обращайтесь с предложениями на сайт компании Телефонные системы, или по e-mail.

Метод DoQuery

Общее описание метода приведено в статье «Базовые элементы интерфейса. DoQuery». В текущем разделе приводится формат параметров при обмене сообщениями в контексте метода.

Параметр (запрос от приложения Oktell к plugin-программе)

Все запросы определяются передаваемым в метод параметром. В текущей версии 2.5-90101 не существует команд, обязательных для реализации в plugin-программе, и ответ в некоем корректном виде вовсе может отсутствовать. В дальнейшем возможно появление обязательных для реализации команд, предполагающих корректный и выверенный ответ plugin-программы.

Запросы всегда состоят из одного элемента property_set, определяющим действие и содержащим необходимые для него параметры. Тип запроса определяется строковым кодом (значением атрибута name) и/или дублирующим числовым кодом (значением атрибута id) элемента property_set. Значения этих атрибутов всегда соответствуют друг другу. Все необходимые для исполнения запроса параметры составляют свойства элемента. В отдельных случаях элемент может иметь сложную структуру, содержать коллекцию вложенных элементов.

Структура параметра-запроса:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="action" count="1">

  <property_set name="..." id="...">

    ...

  </property_set>

</data>

</oktellxmlmapper>

Возвращаемое значение (ответ plugin-программы на запрос приложения Oktell)

В текущей версии 2.5-90101 не существует команд, обязательных для реализации в plugin-программе. А все исполняемые сервисные действия носят характер информационных пересылок в plugin.

При появлении в дальнейшем обязательных команд-действий структура ответа должна соответствовать приведенному виду, где в теле элемента property_set содержится контекстно-зависимое содержимое.

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="actionresult" count="1">

  <property_set name="..." id="...">

    ...

  </property_set>

</data>

</oktellxmlmapper>

Допустимые типы запросов

tabchange (20101)

formshow (20201)

formhide (20202)

phoneevent (20301)

pluginloaded (20401)

· tabchange

Код 20101. Переводит событие о смене вкладки в заголовке управляющего отображением модуля в plugin-программу. Вызывается только с указанием кода экземпляра формы и только в режиме отображения внешних модулей.

Структура передаваемого запроса:

<property_set name="tabchange" id="20101">

<property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />

<property_simple key="idform" value="817d77a7-5d0e-4783-9304-e310c2ac3443" />

<property_simple key="idshow" value="2e2d8ff0-de47-415f-ab68-9bddcd09952b" />

<property_simple key="actiontype" value="20101" name="TabChange" />

<property_simple key="activeindex" value="3" />

</property_set>

Параметры idplugin, idform, idshow указывают управляющему объекту plugin-программы на конкретный экземпляр отображаемой формы, activeindex указывает индекс вкладки (согласно индексам, определенных в коллекции-перечислении), которая стала активной после действий пользователя (щелчка мышью). Индекс вкладки определяется при генерации события tabs на отображение вкладок обратного метода OnQuery.

· formshow

Код 20201. Переводит событие о начале визуальной работы с формой в plugin-программу. Генерируется каждый раз, когда пользователь открывает модуль из состояния скрытых. Вызывается только с указанием кода экземпляра формы и только в режиме отображения внешних модулей. При смене отображения сначала открываемый модуль создается, затем управляющий объект получает команду formshow, лишь затем генерируется formhide для скрываемого модуля.

<property_set name="formshow" id="20201">

<property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />

<property_simple key="idform" value="817d77a7-5d0e-4783-9304-e310c2ac3443" />

<property_simple key="idshow" value="2e2d8ff0-de47-415f-ab68-9bddcd09952b" />

<property_simple key="actiontype" value="20201" name="FormShow" />

</property_set>

Параметры idplugin, idform, idshow указывают управляющему объекту plugin-программы на конкретный экземпляр отображаемой формы

· formhide

Код 20202. Переводит событие о завершении визуальной работы с формой в plugin-программу. Генерируется каждый раз, когда пользователь проводит в приложении Oktell действия, вызывающие скрытие указанного модуля (перевод в невидимые). Вызывается только с указанием кода экземпляра формы и только в режиме отображения внешних модулей. При смене отображения сначала открываемый модуль создается, затем управляющий объект получает команду formshow, лишь затем генерируется formhide для скрываемого модуля.

<property_set name="formhide" id="20202">

<property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />

<property_simple key="idform" value="817d77a7-5d0e-4783-9304-e310c2ac3443" />

<property_simple key="idshow" value="2e2d8ff0-de47-415f-ab68-9bddcd09952b" />

<property_simple key="actiontype" value="20201" name="FormHide" />

</property_set>

Параметры idplugin, idform, idshow указывают управляющему объекту plugin-программы на конкретный экземпляр отображаемой формы

· phoneevent

Код 20301. Событийное направление, подлежащее подписке. То есть передается в плагин-программу только тогда, когда она предварительно запросила подписку на направление путем вызова OnQuery-метода sethandleevent.

К данному направлению относится ряд событий аппаратного модуля и логики АТС по управлению каналом, связанным с рабочим местом, на котором исполняется plugin-программа.

Типы событий:

HALSrvRegSuccess                = 201 //подключение устройства к серверу

HALSrvRegTimeout                = 202 //таймаут или неудача регистрации устройства на сервере

HALDeviceFound                = 203 //подключение нового устройства

HALDeviceLost                = 204 //потеря текущего устройства

HALHeadsetParams                = 212 //смена состояния гарнитуры (ishookup, isringing)

  CommutationStarted        = 231 //начало коммутации с участием канала

CommutationStopped        = 232 //завершение коммутации с участием канала

FaxStarted                        = 233 //начало факс-сеанса на оппозитном канале

FaxStopped                        = 234 //завершение факс-сеанса на оппозитном канале

FaxFilesReceived                = 235 //получение файлов по встроенному факсу

RingStarted                        = 236 //начало вызова канала

RingFinished                = 237 //прекращение вызова канала

ACMStarted                        = 238 //начало сеанса автодозвона

ACMFinished                        = 239 //завершение сеанса автодозвона

FlashHoldAction                = 240        //смена состояния flash-буфера

ChainStateChange                = 241 //смена состояния текущей цепочки коммутаций

LineStateChange                = 242 //смена состояния канала

Коды и параметры событий соответствуют идентичным событиям сервисного оповещения COM-интеграции (разделы «Сервисное оповещение» и более подробно «Работа с логикой АТС. События АТС по линии пользователя»).

Пример параметра для события CommutationStarted о начале коммутации канала пользователя с каналом другого абонента или IVR:

<property_set name="phoneevent" id="20301">

<property_simple key="actiontype" value="20301" name="PhoneEvent" />

<property_simple key="event" value="231" name="CommutationStarted" />

<property_simple key="idchain" value="abcdef12-abcd-abcd-1234-1234567890ab" />

  <property_simple key="idconnection" value="12345678-1234-1234-1234-abcdef123456" />

  <property_simple key="canfax" value="1" />

  <property_simple key="opponentdescription" value="Иванов Сергей" />

  <property_simple key="opponentname" value="Иванов Сергей" />

  <property_simple key="opponentnumber" value="" />

  <property_simple key="opponentlineid" value="cf8330f4-a0bf-4779-9539-ab8ea6c49df7" />

  <property_simple key="opponentlinenumber" value="" />

</property_set>

· pluginloaded

Код 20401. Вызывается после создания и загрузки plugin-программ, стартующих в режиме без визаулизации вместе с запуском клиентского приложения (устанавливается при регистрации).

<property_set name="pluginloaded" id="20401">

<property_simple key="actiontype" value="20401" name="PluginLoaded" />

</property_set>

Список возможных сервисных команд будет пополняться. В случае, если вам необходимо получить дополнительный функционал, обращайтесь с предложениями на сайт компании Телефонные системы, или по e-mail.


Объектная модель XML-парсера

Объектная модель

Для удобства работы со строковыми XML параметрами разработчику изначально доступны исходные коды классов для преобразования строки установленного формата в структуру объектов, для которых доступны методы преобразования из строки и приведения к строке.

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

Объектная модель представлена тремя видами объектов-данных (по аналогии с используемым форматом структуры XML) и вспомогательного класса для преобразований.

Объект класса CMapperXmlItem представляет собой набор данных, описывающих одно свойство (соответствует элементам XML-структуры property_simple или property_cdata) и содержит поля Key, Value, Name, которые отражают значения соответствующих атрибутов у элементов с тэгами <property_...>. Значение поля CDATA элемента property_cdata также попадает в поле Name объекта. С точки зрения объектной модели при разборе строки XML не делается различий между property_simple и property_cdata. Однако у объекта есть дополнительное поле Type, которое определяет тип преобразования из объектной модели в строку с XML структурой. Тип CDATA рекомендуется к использованию для свойств, имеющих большой или неизвестный заранее объем или формат текстовых данных. При работе с объектами для формирования строки можно самостоятельно устанавливать подходящий для конкретного случая тип свойства. А можно пользоваться уже встроенным статическим методом класса GetItem для автоматического определения типа по данным. При разборе значений можно пользоваться статическими методами класса GetValueName (возвращает значение поля Value, а если оно пусто, то Name) и GetNameValue (наоборот).

Объект класса CMapperXmlItemSet представляет собой набор свойств (соответствует элементу property_set), перечисленных в порядке следования безразлично к уникальности ключей. Объект класса имеет также поля Id и IdName, которые соответствуют атрибутам id и name элемента XML-структуры property_set. Дополнительно объект имеет поле Subsets - коллекция (объект класса CMapperXmlItemSetCollection), содержащая набор вложенных объектов CMapperXmlItemSet.

Объект класса CMapperXmlItemSetCollection (соответствует элементу property_collection) представляет собой набор объектов CMapperXmlItemSet, перечисленных в порядке следования безразлично к другим способам идентификации. Объект имеет поле IdName, соответствующее атрибуту name. Атрибут count в соответствующем элементе структуры XML отражает количество вложенных вложенных объектов CMapperXmlItemSet.

Класс СMapperXmlTransformer имеет только статические методы для преобразований из объектов в строку и наоборот.

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

Исходный код классов приведен в файле Xml.cs демонстрационной plugin-программы. Далее в этом разделе будет разъяснено на примере как производить работу с классами для создания строки с XML-структурой требуемого образца, а также обратной операции разбора параметров XML.

Формирование XML-строки требуемого образца

Рассмотрим на примере, как организовать код на C# для работы с объектной моделью. Решается задача формирования XML строки, имеющей следующий вид:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="input" count="2">

  <property_set>

    <property_simple key="paramkey" value="arbitraryarg" />

    <property_simple key="paramtype" value="4" name="argument" />

    <property_cdata key="paramname"><![CDATA[Имя оператора]]></property_cdata>

    <property_cdata key="paramdescription"><![CDATA[Подставляется в зачитываемый текст]]></property_cdata>

  </property_set>

  <property_set>

    <property_simple key="paramkey" value="categories" />

    <property_simple key="paramtype" value="7" name="fixedlist" />

    <property_cdata key="paramname"><![CDATA[Категории]]></property_cdata>

    <property_cdata key="paramdescription"><![CDATA[Выбор рабочего пространства]]></property_cdata>

    <property_collection name="categories" count="2">

      <property_set name="category" id="0">

        <property_simple key="id" value="0" />

        <property_cdata key="name"><![CDATA[Товары]]></property_cdata>

      </property_set>

      <property_set name="category" id="1">

        <property_simple key="id" value="1" />

        <property_cdata key="name"><![CDATA[Услуги]]></property_cdata>

      </property_set>

    </property_collection>

  </property_set>

</data>

</oktellxmlmapper>

В XML структуре на первом уровне находятся 2 элемента property_set, не имеющие атрибутов, а имеющие только свойства (property_simple и property_cdata), второй элемент содержит коллекцию из двух субэлементов. У этих субэлементов присутствуют атрибуты имени и идентификатора.

Организация кода с использованием описанной объектной модели производится следующим образом:

//Создание главной коллекции, преобразование которой в XML будет производиться

CMapperXmlItemSetCollection coll = new CMapperXmlItemSetCollection ();

//Объявление переменных

CMapperXmlItemSet iset = null;

CMapperXmlItemSet isubset = null;

//Первый элемент коллекции (набор)

//  Подробный комментарий

//Создание объекта

iset = new CMapperXmlItemSet ( );

//Добавление в необходимую коллекцию (в данном случае в основную)

coll.Add ( iset );

//Формирование свойств элемента-набора

//  Происходит с помощью автоматического определения типа (simple/cdata)

//<property_simple key="paramkey" value="arbitraryarg"/>

iset.Add ( CMapperXmlItem.GetItem ( "paramkey", "arbitraryarg" ) );

//<property_simple key="paramtype" value="4" name="argument"/>

iset.Add ( CMapperXmlItem.GetItem ( "paramtype", 4, "argument" ) );

//<property_simple key="paramname"><![CDATA[Имя оператора]]></property_cdata>

iset.Add ( CMapperXmlItem.GetItem ( "paramname", "Имя оператора" ) );

//<property_simple key="paramdescription"><![CDATA[Подставляется в зачитываемый текст]]></property_cdata>

iset.Add ( CMapperXmlItem.GetItem ( "paramdescription", "Подставляется в зачитываемый текст" ) );

//Второй элемент коллекции (набор)

iset = new CMapperXmlItemSet ( );

coll.Add ( iset );

iset.Add ( CMapperXmlItem.GetItem ( "paramkey", "categories" ) );

iset.Add ( CMapperXmlItem.GetItem ( "paramtype", 7, "fixedlist" ) );

iset.Add ( CMapperXmlItem.GetItem ( "paramname", "Категории" ) );

iset.Add ( CMapperXmlItem.GetItem ( "paramdescription", "Выбор рабочего пространства" ) );

//У второго элемента есть вложенные

//  Происходит формирование коллекции вложенных элементов

//Задание свойства name вложенной коллекции

iset.SubSets.Name = "categories";

//Первый подэлемент

isubset = new CMapperXmlItemSet ( );

iset.SubSets.Add ( isubset );

isubset.Name = "category";

isubset.IdName = "0";

isubset.Add ( CMapperXmlItem.GetItem ( "id", "0" ) );

isubset.Add ( CMapperXmlItem.GetItem ( "name", "Товары" ) );

//Второй подэлемент

isubset = new CMapperXmlItemSet ( );

iset.SubSets.Add ( isubset );

isubset.Name = "category";

isubset.IdName = "1";

isubset.Add ( CMapperXmlItem.GetItem ( "id", "1" ) );

isubset.Add ( CMapperXmlItem.GetItem ( "name", "Услуги" ) );

//Преобразование коллекции (объекта) к XML-строке

return coll.WriteToXml ( "input" );

Парсинг XML-строки

Рассмотрим на примере, как организовать код на C# для работы с объектной моделью. Решается задача выделения нужных параметров из простейшей XML-строки установленного образца, имеющей следующий вид:

<?xml version="1.0" encoding="utf-16"?>

<oktellxmlmapper version="80710">

<data name="action" count="1">

  <property_set id="20101" name="tabchange">

    <property_simple key="idplugin" value="12341234-abcd-abcd-abcd-abcdabcdabcd" />

    <property_simple key="idform" value="f031ea44-7299-a173-4b1b-238fe1200c3" />

    <property_simple key="idshow" value="2e2d8ff0-de47-415f-ab68-9bddcd09952b" />

    <property_simple key="actiontype" value="20101" name="TabChange" />

    <property_simple key="activeindex" value="6" />

  </property_set>

</data>

</oktellxmlmapper>

Это строковый параметр, передаваемый в метод DoQuery для обработки события клиентского приложения о факте смены вкладки в заголовке модуля. Метод DoQuery принадлежит управляющему объекту, поэтому он должен выделить параметры: Код формы и экземпляра (для того чтобы перенаправить команду в нужном направлении, так как открытых форм может быть много), а также тип события и его параметр (в данном случае тип - смена вкладки, а параметр - код вкладки).

Очевидно, что приведенный пример - частный случай и не может в чистом виде быть использован. Необходима полная обработка возможных вариантов (конкретнее можно посмотреть в демонстрационно примере plugin-программы).

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

//Коллекция с запросом на основе XML-строки

CMapperXmlItemSetCollection coll = CMapperXmlItemSetCollection.FromXml ( xml );

if ( coll == null )

{

//Если что-то не корректно - соответствующая обработка

}

else

{

//Коллекция без ошибок была преобразована к объектной модели

//Цикл по всем наборам основной коллекции.

//  В зависимости от поставленной задачи:

//  - либо ищем необходимый блок

//       (тогда пропускаем все другие)

//  - либо обрабатывается/преобразуется вся структура

//       (тогда в теле цикла по мере разбора производим обработку)

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

//   Тогда объединяется процедура разбора и создания ответа (зависимо в едином теле цикла)

for ( int i1 = 0; i1 < coll.Count; i1++ )

{

   CMapperXmlItemSet iset = coll [ i1 ];

   //Необходимо обеспечить стабильность кода проверками корректности при преобразованиях,

   //  либо включить код в блок обработки исключений try..catch

   //  Например, если в поле, где заявлен для указания GUID, содержится некорректная строка

   try

   {

     //По имени набора определяется запрошенное действие

     //  (атрибут name тега property_set)

     switch ( iset.Name.ToLower() )

     {

       case "tabchange"://команда смены вкладки

         //Объявляем переменные, которые необходимы для обработки события

         Guid idplugin = Guid.Empty;

         Guid idform = Guid.Empty;

         Guid idshow = Guid.Empty;

         int index = -1;

         //Сначала в цикле обрабатываются все свойства поочередно

         //  безотносительно типа (property_simple/property_cdata)

         //  И только потом производится передача управления в метод обработки команды

         for ( int i2 = 0; i2 < iset.Count; i2++ )

         {

           //Объект - свойство

           CMapperXmlItem item = iset [ i2 ];

           //По значению атрибута key определяется что именно представляет из себя свойство

           //  В теле блока switch идет разбор только известных команд. Остальные пропускаются.

           switch ( item.Key.ToLower() )

           {

             case "idplugin"://свойство идентификатора plugin-программы

               idplugin = new Guid ( CMapperXmlItem.GetValueName ( item ) );

             break;

             case "idform"://свойство идентификатора plugin-формы

               idform = new Guid ( CMapperXmlItem.GetValueName ( item ) );

             break;

             case "idshow"://свойство идентификатора экземпляра plugin-формы

               idshow = new Guid ( CMapperXmlItem.GetValueName ( item ) );

             break;

             case "activeindex"://идентификатор выбранной вкладки

               index = int.Parse ( CMapperXmlItem.GetValueName ( item ) );

             break;

           }

         }

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

         //Элементарная проверка задания всех необходимых свойств

         if (( index < 0 ) || ( idform == Guid.Empty ) || ( idshow == Guid.Empty ))

         {

           //Обработка ошибки и выход

           break;

         }

         //При необходимости проверка корректности задания свойств

         //  (наличие формы среди открытых, наличие указанной вкладки)

         //Обработка команды смены вкладки.

         //  Это внутренний вызов, может быть реализован любым способом.

         ActionChangeTab ( idform, idshow, index );

       break;

     }

   }

   catch ( Exception ex )

   {

     //Исключение при обработке.

   }

}

}


Пример plugin-сборки

 Содержание | Назад | Далее

Вы можете обратиться к примеру. Скачать его можно на FTP сервере ftp://oktell.ru. Уточняйте в службе технической поддержки.


Звонок с терминала

В этом разделе:

— Цели и задачи

— Варианты реализации

— Подключение к COM-объекту

— Регистрация библиотеки

— Интерфейс взаимодействия

— Использование native win32 библиотеки

— Интерфейс взаимодействия

— Использование .NET сборки

— Интерфейс взаимодействия


Подключение к COM-объекту

Подключение через COM

 Содержание | Назад | Далее

Работа с COM-объектом считается устаревшей и не поддерживает ряд методов, в частности работу с видео сессиями. Развитие COM-библиотеки приостановлено. Взамен была предложена альтернатива по работе с native win32 библиотекой.


Регистрация библиотеки

Регистрация COM-библиотеки

COM объект представлен одной библиотекой (SipClient.dll). Его регистрация осуществляется стандартным способом при помощи утилиты regsvr32.exe.

Команда для исполнения регистрации выглядит:

regsvr32 SipClient.dll

либо

путь\regsvr32 путь\SipClient.dll

Команда для удаления регистрации:

regsvr32 /u SipClient.dll

После успешной регистрации (о чем будет сообщено дополнительно в диалоговом окне), в списке доступных COM-объектов будет присутствовать и объект SipClientObj.

Регистрация объекта скорее всего должна производиться в момент установки приложения.

Информация о COM-объекте

Полное имя объекта: SipClientObj

GUID объекта: 2E6048CC-CCE1-4DEA-BB30-76BC3CEB92A1

Интерфейс для вызова методов: interface ISipClient

GUID интерфейса: F75E3D25-9095-4152-87DF-DF85ECFBD553

Интерфейс для callback-методов: dispinterface _ISIPClientEvents

GUID интерфейса: CDFD5DB2-2C32-425E-A95E-D330B9EF9D5A

Библиотека: SipClient 1.0 Type Library

GUID библиотеки: 8A4C2812-8D07-49D2-BD1A-1B66400C8E29


Интерфейс взаимодействия

Используемые наборы-перечисления

Поддерживаемые кодеки

typedef enum

{

SIPCODEC_G711A,

SIPCODEC_G711U,

SIPCODEC_GSM,

SIPCODEC_G729,

} SIPCODEC;

Состояния SIP-клиента

typedef enum

{

SIPSTATE_IDLE, // состояние покоя

SIPSTATE_CONNECTING, // производится соединение с сервером (передача информации)

SIPSTATE_CONNECTED, // связь с сервером установленна - переход к вызову оператора

SIPSTATE_CALLING, // вызов оператора

SIPSTATE_INCALL, // в разговоре

SIPSTATE_DISCONNECTING, // разрыв соединения

} SIPSTATE;

Интерфейс обращений ISIPClient

Настройка параметров вызова. Применение происходит до осуществления звонка. Настоятельно не рекомендуется изменять значения во время сеанса связи.

HRESULT SetupSIPAccount ( [in] BSTR szDomain, [in] BSTR szSIPProxy, [in] BSTR szRemoteId, [in] BSTR szUserId, [in] BSTR szUserName, [in] BSTR szUserInfo)

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

szDomain имя сервера (например: myhost.ru)
szSIPProxy ip адрес или днс имя сервера с опциональным портом (например: myhost.ru, 212.333.111.213:5070)
порт по умолчанию 5060
szRemoteId идентификатор вызываемой службы (должно совпадать с соответствующим параметром в карте)
szUserId идентификатор клиента (произвольно, но не пустой)
szUserName не обязательное имя клиента
szUserInfo информация которую необходимо передать на сервер (при передаче кодируется в utf-8)

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

HRESULT SIPDomain ( [out, retval] BSTR* pVal )

HRESULT SIPDomain ( [in] BSTR newVal )

HRESULT SIPProxy ( [out, retval] BSTR* pVal )

HRESULT SIPProxy ( [in] BSTR newVal )

HRESULT RemoteId ( [out, retval] BSTR* pVal )

HRESULT RemoteId ( [in] BSTR newVal )

HRESULT UserId ( [out, retval] BSTR* pVal )

HRESULT UserId ( [in] BSTR newVal )

HRESULT UserName ( [out, retval] BSTR* pVal )

HRESULT UserName ( [in] BSTR newVal )

HRESULT UserInfo ( [out, retval] BSTR* pVal )

HRESULT UserInfo ( [in] BSTR newVal )

Настройки звуковой подсистемы. Применение происходит до осуществления звонка. Настоятельно не рекомендуется изменять значения во время сеанса связи.

HRESULT GetSpkDevCount ( [out, retval] int* pCount )

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

HRESULT GetSpkDeviceAt ( [in] int nIndex, [out, retval] BSTR* pszDeviceName )

Возвращает название устройства вывода звука (динамика) по порядковому индексу. Используется в дальнейшем для установки устройства функцией SetupVoiceDevice.

HRESULT GetMicDevCount ( [out, retval] int* pCount )

Возвращает количество доступных устройств ввода звука (микрофонов).

HRESULT GetMicDeviceAt ( [in] int nIndex, [out, retval] BSTR* pszDeviceName )

Возвращает название устройства ввода звука (микрофона) по порядковому индексу. Используется в дальнейшем для установки устройства функцией SetupVoiceDevice.

HRESULT SetupVoiceDevice ( [in] BSTR szSpkDevice, [in] BSTR szMicDevice, [in] SIPCODEC prefCodec )

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

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

HRESULT SelectedSpkDevice ( [out, retval] BSTR* pVal )

Возвращает текущее выбранное устройство вывода звука (динамик).

HRESULT SelectedSpkDevice ( [in] BSTR newVal )

Устанавливает текущее выбранное устройства вывода звука (динамик). Отдельная альтернатива функции SetupVoiceDevice.

HRESULT SelectedMicDevice ( [out, retval] BSTR* pVal )

Возвращает текущее выбранное устройство ввода звука (микрофон).

HRESULT SelectedMicDevice ( [in] BSTR newVal )

Устанавливает текущее выбранное устройства вывода звука (динамик). Отдельная альтернатива функции SetupVoiceDevice.

HRESULT PreferredCodec ( [out, retval] SIPCODEC* pVal )

Возвращает текущий выбранный предпочитаемый кодек.

HRESULT PreferredCodec ( [in] SIPCODEC newVal )

Устанавливает текущий выбранный предпочитаемый кодек. Отдельная альтернатива функции SetupVoiceDevice.

Управление вызовом.

HRESULT Call ( [out, retval] VARIANT_BOOL* pRes )

Осуществление вызова (соединение по TCP с сервером, передача szUserInfo, после положительного ответа совершается звонок оператору по UDP). Предварительно необходимо установить параметры вызовом SetupSIPAccount.

HRESULT Hungup ( void )

Завершает текущее активное соединение.

HRESULT SentDTMF ( [in] CHAR chDTMF, [out, retval] VARIANT_BOOL* pRes )

Генерирует и отправляет DTMF сигнал на сервер. Может пригодиться для взаимодействия с голосовым меню и ввода дополнительной информации.

Не реализованные функции.

HRESULT SendUserMessage ( [in] BSTR szMessage )

Отправляет текстовое сообщение в ходе разговора.

HRESULT SetupSocksServer ( [in] BSTR szSocksAddress, [in] WORD wPort, [in] BSTR szSocksUser, [in] BSTR szSocksPassword )

Настройка SOCKS на случай невозможности определить автоматом. В текущей реализации объект может осуществлять вызов только через NAT или через прямое подключение к интернет.

Интерфейс событий _ISIPClientEvents

void OnCallConnected ( [in] BSTR info )

Соединение прошло успешно. Объект находится в разговоре.

void OnCallRejected ( [in] BSTR reason )

Вызов отклонен. В строке-параметре передается информация о причине отказа.

void OnCallFinished ( [in] VARIANT_BOOL localEnd, [in] BSTR eventInfo )

Вызов завершен. Параметр указывает - локальный

void OnDataSent ( void )

Данные отправлены (только при использовании SendUserMessage - не реализовано).

void OnDataReceive ( [in] BSTR data )

Данные получены (только при использовании SendUserMessage - не реализовано).

void OnError ( [in] BSTR errorText )

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

void OnStateChanged ( [in] SIPSTATE newState )

Изменилось состояние объекта. Параметр передает новое состояние из приведенного выше набора состояний.


Использование native win32 библиотеки

Подключение native win32 библиотеки

 Содержание | Назад | Далее

Работа с native Win32 библиотекой SipClientLib.dll предоставляет полную функциональность интеграционной схемы, за исключением работы с камерами для отправки видео-изображения на сервер в ходе установленной сессии. Библиотека принимает на вход изображения, которые необходимо получать в стороннем ПО и передавать ей для отправки на сервер в заданные интервалы времени.

В этом разделе:

— Интерфейс взаимодействия с .NET-сборкой


Интерфейс взаимодействия

Перечисления

Возможные состояния телефона (транка):

enum SIP_STATE

{

SIP_STATE_IDLE = 0, // телефон
SIP_STATE_CONNECTING = 1, // соединение по tcp
SIP_STATE_CONNECTED = 2, // соединение по tcp установленно
SIP_STATE_CALLING = 3, // телефон начал вызов по сип
SIP_STATE_INCALL = 4, // телефон в разговоре
SIP_STATE_DISCONNECTING = 5, // разрыв соединения

};

Поддерживаемые аудио кодеки:

enum SIP_CODEC

{

SIP_CODEC_G711A = 0,

SIP_CODEC_G711U = 1,

SIP_CODEC_GSM = 2,

SIP_CODEC_G729 = 3,

};

События (callback-методы)

С++:

typedef DWORD (__stdcall *PFN_SIPCLIENT_EVENTS)(SIP_CALLBACK event, DWORD dwParam, LPCWSTR wzParam);

Возможные типы событий

enum SIP_CALLBACK

{

SIP_CALL_CONNECTED = 0, // вызов принят : dwparam - 0, szparam - текстовое описание
SIP_CALL_REJECTED = 1, // вызов отвергнут : dwparam - код ошибки (SIP), szparam - текстовое описание
SIP_CALL_FINISHED = 2, // вызов завершен : dwparam - инициатор разрыва (1 - localEnd, 0 - remoteEnd),zparam - текстовое описание
SIP_DATA_SENT = 3, // файл отправлен : dwparam - handle потока
SIP_DATA_ERROR = 4, // ошибка отправки файла: dwparam - handle потока, szparam - текстовое описание
SIP_DATA_INCOME = 5, // принят запрос на прием файла, параметры: dwParam - handle для потока, wzparam - описание потока.
SIP_DATA_RECEIVED = 6, // данные приняты : dwparam - handle потока
SIP_ERROR = 7, // ошибка соединения : dwparam - код ошибки (SIP), szparam - текстовое описание
SIP_STATE_CHANGED = 8, // изменено состояние телефона : dwParam - новое состояние
SIP_VIDEO_FRAME_READY = 9, // получен следующий видео-кадр : dwparam - HBITMAP нового кадра
SIP_VIDEO_STARTED = 10, // видео связь установленна
SIP_VIDEO_PAUSED = 11, // входящий видео поток в паузе/остановлен

};

Методы

Инициализация и уничтожение

SIP_API BOOL __stdcall InitSipClientLib ( PFN_SIPCLIENT_EVENTS ); Инициализация библиотеки.

SIP_API void __stdcall FreeSipClientLib ( ); Очистка, освобождение ресурсов и завершение работы библиотеки.

Осуществление вызовов

SIP_API BOOL __stdcall Call ( LPCWSTR szMessage ); Запрос исходящего вызова на соединение с сервером и создания голосовой сессии (соединение по TCP каналу с сервером, передача szUserInfo, при получении положительного ответа совершается звонок на сервер и голосовое соединение с главным сценарием).

SIP_API void __stdcall Hungup ( ); Завершает активное соединение.

SIP_API BOOL __stdcall SentDTMF ( CHAR chDTMF ); Отправляет DTMF сигнал на сервер в ходе активной голосовой сессии.

Передача файлов

SIP_API HANDLE __stdcall StartSending ( LPCWSTR szTag, BYTE* pData, int size, BOOL bEOF, int* pSent ); Инициирует отправку файла на сервер в ходе активной сессии связи. Если файл достаточно больших размеров, то запрашивает для первого блока файла с последующим вызовом метода SendBlock для отправки других частей файла или AbortSending для прекращения отправки.

Параметры:

szTag - строка с XML-содержимым, описывающим передаваемый файл. (<fileinfo><key=filesize,

pData - ссылка на буфер с содержимым первой части файла.

size - размер буфера с содержимым в байтах.

bEOF - признак последней отправки (если считана и передается последняя часть файла).

pSent - возвращает количество отправленных байтов.

Возвращаемое значение - адрес сессии передачи файла для последующего обращения к сессии методами SendBlock или AbortSending.

SIP_API int __stdcall SendBlock ( HANDLE handle, BYTE* pData, int size, BOOL bEOF ); Инициирует отправку второй и последующих частей файла в ходе одной сессии.

Параметры:

handle - адрес сессии, определенный при вызове метода StartSending.

pData - ссылка на буфер с содержимым первой части файла.

size - размер буфера с содержимым в байтах.

bEOF - признак последней отправки (если считана и передается последняя часть файла).

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

SIP_API void __stdcall AbortSending ( HANDLE handle ); Обрывает сессию отправки файла. Параметр указывает на адрес сессии, определенный при вызове метода StartSending.

SIP_API BOOL __stdcall ReceiveBlock ( HANDLE handle, BYTE* pData, int size, int* pRecv ); Получает очередной блок файла. В текущей реализации не используется.

SIP_API void __stdcall AbortReceiving ( HANDLE handle ); Обрывает сессию получения файла. В текущей реализации не используется.

Запись в лог-журнал

SIP_API void __stdcall LogWrite ( LPCWSTR szTag, LPCWSTR szString); Осуществляет запись в лог-журнал, ведущийся библиотекой.

Установка параметров SIP-клиента

SIP_API BOOL __stdcall SetupSIPAccount ( LPCWSTR szDomain, LPCWSTR szSIPProxy, LPCWSTR szRemoteId, LPCWSTR szUserId, LPCWSTR szUserName, LPCWSTR szUserInfo); Устанавливает параметры SIP-клиента для последующего совершения исходящих звонков.

Параметры:

szDomain - имя сервера (например: «myhost.ru», «192.168.0.10», и т.д. )

szSIPProxy - IP-адрес или DNS-имя сервера с опциональным портом (например: «myhost.ru», «212.333.111.213:5070»). Порт по умолчанию 5060.

szRemoteId - идентификатор вызываемой службы (должно совпадать с соответствующим параметром в карте).

szUserId - идентификатор абонента (userid) - составная часть sip-адреса user@domain, определяемого сервером как CallerId. Может содержать латинские буквы, цифры, точки и прочие символы, которые могут быть использованы в именах e-mail до символа «@».

szUserName - необязательное имя клиента.

szUserInfo - информация, которую необходимо передать на сервер (при передаче кодируется в utf-8). Строка с любым (возможно XML) содержимым, которая становится доступна серверу в функции сценариев IVR «XML-INFO абонента» и используется для маршрутизации вызова или начального заполнения диалоговых форм оператора или БД.

Возвращаемое значение указывает на успешность выполнения операции.

Установка и получение параметров по отдельности. Применение происходит до осуществления звонка (клиент должен находится в состоянии IDLE). Каждая функция устанавливает значение полей, соответствующих параметрам функции SetupSIPAccount.

SIP_API BOOL __stdcall GetSIPDomain ( LPWSTR pBuff, int cch );

SIP_API BOOL __stdcall SetSIPDomain ( LPCWSTR newVal );

SIP_API BOOL __stdcall GetSIPProxy ( LPWSTR pBuff, int cch );

SIP_API BOOL __stdcall SetSIPProxy ( LPCWSTR newVal );

SIP_API BOOL __stdcall GetRemoteId ( LPWSTR pBuff, int cch );

SIP_API BOOL __stdcall SetRemoteId ( LPCWSTR newVal );

SIP_API BOOL __stdcall GetUserId ( LPWSTR pBuff, int cch );

SIP_API BOOL __stdcall SetUserId ( LPCWSTR newVal );

SIP_API BOOL __stdcall GetUserName ( LPWSTR pBuff, int cch );

SIP_API BOOL __stdcall SetUserName ( LPCWSTR newVal );

SIP_API BOOL __stdcall GetUserInfo ( LPWSTR pBuff, int cch );

SIP_API BOOL __stdcall SetUserInfo ( LPCWSTR newVal );

Настройка звуковой подсистемы

SIP_API BOOL __stdcall SetupVoiceDevice ( LPCWSTR szSpkDevice, LPCWSTR szMicDevice, SIP_CODEC prefCodec ); Устанавливает устройства вывода звука (динамик), ввода звука (микрофон) и выбор используемого аудио-кодека.

SIP_API int __stdcall GetSpkDevCount ( ); Возвращает количество устройств вывода звука (динамиков) в системе.

SIP_API BOOL __stdcall GetSpkDeviceAt ( int nIndex, LPWSTR pszDeviceName, int cch ); Возвращает имя устройства вывода звука (динамика) по индексу перечисления в системе.

SIP_API int __stdcall GetMicDevCount ( ); Возвращает количество устройств ввода звука (микрофонов) в системе.

SIP_API BOOL __stdcall GetMicDeviceAt ( int nIndex, LPWSTR pszDeviceName, int cch ); Возвращает имя устройства ввода звука (микрофона) по индексу перечисления в системе.

Установка и получение параметров по отдельности. Применение происходит до осуществления звонка (клиент должен находится в состоянии IDLE). Каждая функция устанавливает значение полей, соответствующих параметрам функции SetupVoiceDevice.

SIP_API BOOL __stdcall GetSelectedSpkDevice ( LPWSTR pBuff, int cch );

SIP_API BOOL __stdcall SetSelectedSpkDevice ( LPCWSTR newVal );

SIP_API BOOL __stdcall GetSelectedMicDevice ( LPWSTR pBuff, int cch );

SIP_API BOOL __stdcall SetSelectedMicDevice ( LPCWSTR newVal );

SIP_API BOOL __stdcall GetPreferredCodec ( SIP_CODEC* pVal );

SIP_API BOOL __stdcall SetPreferredCodec ( SIP_CODEC newVal );

Настройка SOCKS

SIP_API BOOL __stdcall SetupSocksServer ( LPCWSTR szSocksAddress, WORD wPort, LPCWSTR szSocksUser, LPCWSTR szSocksPassword ); Настройка socks на случай невозможности определить автоматом (не реализовано. клиент может звонить только через NAT или напрямую).

Настройка видео

SIP_API BOOL __stdcall SetupVideoCodec ( BOOL bShowDialog ); Открывает окно настроек видео-кодека.

SIP_API BOOL __stdcall StartVideo ( int width, int height ); Начинает прием/передачу видео в ходе текущей активной голосовой сессии с сервером. В качестве параметров принимаются размеры (ширина и высота) кадров.

SIP_API void __stdcall StopVideo ( ); Прекращает прием/передачу видео.

SIP_API BOOL __stdcall SendNextFrame ( HBITMAP hBitmap ); Отправляет видео-фрейм в качестве собственного видео на сервер. Объект уничтожается внутри функции после отправки.


Использование .NET сборки

Подключение .NET-сборки

 Содержание | Назад | Далее

Основной .NET библиотекой является сборка oktell.VideoCallLib.dll.

Зависимыми библиотеками также являются oktell.HAL.dll и SipClientLib.dll.

Для работы используется .NET-класс oktell.HAL.Video.VideoCall, реализованный в библиотеке oktell.VideoCallLib.dll.

Работа с .NET вариантом реализации библиотеки подразумевает использование ее в .NET проектах. Сборка расширяет возможности native win32 библиотеки SipClientLib.dll, описанной в разделе Native Win32 за счет внедрения работы с видео-камерами.

Вся работа с видео-камерами осуществляется в .NET коде. Сборка использует библиотеку SipClientLib.dll.

Сборка может предоставляться в реализации под FrameWork версий 1.1 и 2.0.

В этом разделе:

— Интерфейс взаимодействия с .NET-сборкой


Интерфейс взаимодействия

Методы

void Init ( System.Windows.Forms.Control videoIn, System.Windows.Forms.Control videoOut ). Инициализирует объект oktellVideoCall. В качестве параметров передаются контролы (.NET) для отображения видео-изображений, получаемых с камеры и с сервера.

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

Метод должен быть вызван один раз перед звонком. Звонков можно осуществлять произвольное количество. После использования необходимо выполнить метод Dispose для уничтожения объекта и освобождения ресурсов. В ходе одной сессии работы можно выполнять метод Init несколько раз, если его вызовы каждый раз будут сопровождаться вызовами метода Dispose.

bool Call ( string userData ). Инициирует вызов абонента. Вызов осуществляется по адресам с использованием предварительно установленных свойств (подробнее ниже в подразделе «Свойства»). В качестве параметра передается любое пользовательское строковое значение, которое при поступлении вызова на сервер становится доступным в сценарии IVR в качестве функции «XML-INFO абонента». Параметр может быть использован для передачи контекстной информации в целях маршрутизации вызова на сервере или заполнения БД или диалоговых форм оператора. Непустое значение параметра заменяет значение свойства UserInfo.

Метод выполняется синхронно с приостановкой вызвавшего потока до момента полного запуска процедуры инициации исходящего вызова. Возвращает управление после отправки INVITE-инструкции на сервер, но еще до момента установки голосовой связи. Возвращаемое значение определяет результат выполнения метода: TRUE - вызов успешно начат, FALSE - вызов не инициирован из-за возникших проблем (не заданы настройки, заблокированы порты, не обнаружен сетевой интерфейс и т.д.).

В зависимости от значения свойства VideoIsSet осуществляется голосовой или видео-звонок.

void StopCall ( ). Завершает текущий активный разговор или вызов абонента. Выполняется синхронно с приостановкой вызвавшего потока.

void Dispose (). Уничтожает объект после использования и освобождает ресурсы. После выполнения метода Dispose для осуществления исходящих звонков необходимо вновь выполнить метод Init.

int SendDataStart ( string path ). Начинает отправку файла на сервер. Метод может быть вызван только при активной сессии голосовой связи с сервером. Одновременно могут отправляться множество файлов. Размер буфера чтения для отправки в одной итерации устанавливается свойством UploadBufferSize.

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

Метод выполняется асинхронно.

void SendDataAbort ( int Number ). Прекращает передачу файла, если она активна. Параметр указывает номер сессии передачи файла, определенный при запуске соответствующей сессии методом SendDataStart.

string[] GetVideoInputDevices (). Возвращает список подключенных к терминалу и обнаруженных веб-камер. Метод имеет смысл использовать только в случае, если настраивается отправка видео-потока с веб-камеры.

События

event void OnCallStart ( ). Генерируется при установлении голосовой сессии с сервером. Метод Call возвращает управление после отправки INVITE-инструкции, событие генерируется после ответа CONNECTED. В случае корректных настроек сервера, указания его адреса и полной дееспособности обеих сторон, сервер практически мгновенно выдает этот ответ, поскольку вызов принимается главным сценарием и не зависит от человеческого фактора.

event void OnCallStop ( ). Генерируется при завершении текущей коммутации или прекращенной сессии исходящего вызова.

event void OnError ( int errcode, int errtext ). Генерируется при ошибке, возникающей в ходе исходящей сессии вызова.

Возможные коды и описания ошибок соответствуют ошибкам стандартного HTTP-протокола (400 - bad request, 403 - forbidden, 404 - not found, 503 - service not available, и т.д.).

event void OnSendDataStart ( int num ). Генерируется после первой удачной отправки части файла в сеть в ходе текущей голосовой сессии с сервером.

event void OnSendDataFinish ( int num ). Генерируется при успешном завершении передачи файла.

event void OnSendDataProcess ( int num, int percent ). Генерируется периодически в ходе сессии передачи файла для указания процента выполнения операции относительно размера файла.

event void OnSendDataAbort ( int num ). Генерируется при разрыве передачи файла по инициативе стороннего ПО или сервера.

Свойства

ECameraType CameraType { get; set; }. Устанавливает/возвращает тип устройства для захвата исходящего видео-потока.

None = 0 - исходящее видео игнорируется

IPCam = 1 - исходящее видео с IP-камеры, должны быть заданы Ip-адрес, логин и пароль для подключения к устройству.

WebCam = 2 - исходящее видео с Web-камеры.

string VideoDeviceName { get; set; }. Устанавливает/возвращает название текущей выбранной веб-камеры (название устройства в системе). При подключении нескольких веб-камер может случиться, что их имена в операционной системе будут совпадать. В этом случае будет выбрана первая камера с указанным названием. В случае, если установленное имя не обнаружено среди реально подключенных устройств, будет взято первое доступное. Свойство имеет смысл задать только в случае, если настроено получение видео-потока с веб-камеры.

string CameraIp { get; set; }. Устанавливает/возвращает IP-адрес IP-камеры, с которой необходимо получать видео поток для отправки в качестве собственного изображения. Например «192.168.0.90». Изображение будет отображаться также на окне videoOut, которое было указано в качестве параметра метода Init. Свойство необходимо задать только в случае, если настроено получение видео-потока с IP-камеры.

string CameraUserName { get; set; }. Устанавливает/возвращает логин для базовой авторизации при запросе видео-потока с IP-камеры. Например «root». Свойство необходимо задать только в случае, если настроено получение видео-потока с IP-камеры.

string CameraPassword { get; set; }. Устанавливает/возвращает пароль для базовой авторизации при запросе видео-потока с IP-камеры. Например «pass». Свойство необходимо задать используется только в случае, если настроено получение видео-потока с IP-камеры.

string SpkDevice { get; set; }. Устанавливает/возвращает устройство для вывода звука (динамик) в ходе голосовой сессии с сервером. Указывается строковое название устройства в ОС, например «Logitech USB Headset». В случае, если значение не указано, вывод звука осуществляется в стандартное звуковое устройство.

string MicDevice { get; set; }. Устанавливает/возвращает устройство для ввода звука (микрофон) в ходе голосовой сессии с сервером. Указывается строковое название устройства в ОС, например «Logitech USB Headset». В случае, если значение не указано, вывод звука осуществляется в стандартное звуковое устройство.

string ServerName { get; set; }. Устанавливает/возвращает DNS-имя хоста или IP-адрес сервера, к которому необходимо осуществлять подключение. Может быть указано доменное имя сервера в интернет.

string ServerAddress { get; set; }. Устанавливает/возвращает адрес сервера, куда необходимо отправлять пакеты инициализации SIP-сессии связи с сервером. Фактически это адрес SIP-PROXY.

string UserId { get; set; }. Устанавливает/возвращает идентификатор абонента (userid) - составная часть sip-адреса user@domain, определяемого сервером как CallerId. Может содержать латинские буквы, цифры, точки и прочие символы, которые могут быть использованы в именах e-mail до символа «@».

string ServiceNumber { get; set; }. Устанавливает/возвращает номер, на который осуществлять вызов. В рамках обсуждаемого режима интеграции этот номер будет определен сервером и распознан как набираемый номер. В дополнение к нему на сервере может быть настроен анализ параметра «XML-INFO абонента», передающий произвольную пользовательскую информацию на сервер с терминала.

string UserInfo { get; set; }. Устанавливает/возвращает пользовательский параметр произвольного строкового вида, передаваемый на сервер еще до совершения вызова. Может быть подменена при вызове метода Call с непустым значением параметра. Строка UserInfo при осуществлении вызова не должна быть пустой. Сервер получает доступ к этой переданной информации через функцию «XML-INFO абонента» сценариев IVR.

int VideoCompression { get; set; }. Устанавливает/возвращает степень сжатия изображений кодеком (0-100). Значение «-1» не изменяет текущие установки самой камеры.

System.Drawing.Size Resolution { get; set; }. Устанавливает/возвращает разрешение видео-изображения, передаваемое с камеры терминала на сервер, например «new Size (176, 144)».

int VideoBufferSize { get; set; }. Устанавливает/возвращает размер буфера в байтах для считывания видео с камеры, например 2048. Значение «0» устанавливает размер буфера по умолчанию.

int UploadBufferSize { get; set; }. Устанавливает/возвращает размер буфера в байтах для итерации чтения файла и загрузки на сервер, например 65536. Значение «0» устанавливает размер буфера по умолчанию.


Тестовое приложение

 Содержание | Назад | Далее

Вы можете обратиться к примеру. Скачать его можно на FTP сервере ftp://oktell.ru. Уточняйте в службе технической поддержки.


Дополнительно

В этом разделе:

— Локальные устройства. Телефон

— Возможные проблемы и способы их устранения

— Структура пространственной БД

— Порты, используемые системой

— Параметры файлов конфигурации

— Форматы звуковых файлов

— Порядок обновления программы в ручном режиме


Локальные устройства. Телефон

Звонки и сервис автодозвона

Пользователи, имеющие в своем распоряжении аналоговый или IP-телефон (а не управляемый компьютером модуль подключения Voip-телефонов) через модуль «Телефон» имеют доступ к сервису автодозвона. При наборе номера и нажатии единственной в этом случае кнопки «Позвонить», сервер начинает дозвон до указанного номера. Если набранный номер существует среди внутренних стандартных номеров АТС Oktell, то сервер встанет в очередь до момента снятия трубки на той стороне. В противном случае осуществляется набор номера в город (наружу), используя свободную и доступную текущему пользователю внешнюю линию. При этом если номер занят или не отвечает, сервер осуществляет повтор набора. Число попыток, а также длительность ожидания в различных ситуациях настраиваются администратором в модуле «Общие настройки. Параметры автодозвона».

Чтобы позвонить, используя сервис автодозвона:

· Выберите из выпадающего списка набранных номеров необходимый номер и нажмите «Позвонить».
· Наберите номер с помощью клавиатуры в поле «Номер» выпадающего списка и нажмите «Позвонить».
· Наберите номер, щелкая мышью на цифровых кнопках модуля, и нажмите «Позвонить».
· В модуле «Офис. Сотрудники» выберите необходимый номер и нажмите кнопку «Позвонить» или выберите соответствующий пункт контекстного меню.
· В модуле «Офис. Клиенты» выберите необходимого клиента и нажмите кнопку «Позвонить» или выберите соответствующий пункт контекстного меню.

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

Снятием трубки при активном сеансе автодозвона производится прекращение работы сервиса и перевод текущего вызова на линию пользователя. В линию пользователя в любом случае выводится сигнал КПВ до момента получения ответа на вызываемом канале. Режим не действует для SIP без назначенного номера hotline.

Сеанс автодозвона можно прервать в любой момент подняв и положив трубку телефонного аппарата (не действует для SIP без назначенного номера hotline) или нажатием кнопки «Отменить», появляющейся на панели в момент активности сервиса.

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

Во время любой коммутации на панели телефона отображена информация о текущем звонке: абонент на другой стороне и время разговора. Если происходит удержание некоторого абонента во флеш-буфере, то информация о нем также отображается.

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

Для возврата к абоненту, находящемуся на удержании, необходимо нажать кнопку «Завершить», или FLASH на телефонном аппарате. Чтобы осуществить переключение и соединить обоих абонентов между собой необходимо нажать кнопку «Соединить» или положить трубку на телефонном аппарате.

Выбор аудио-устройств. Гарнитура

При работе с гарнитурами, USB-телефонами и прочими устройствами, управлением которых занимается модуль подключения VoIP-телефонов (программный шлюз Oktell), функционал модуля расширяется. При этом все описанные выше сервисы остаются также доступны.

В заголовке модуля «Телефон» отображена пиктограмма гарнитуры, нажатием на которую вызывается диалоговое окно выбора устройств. Окно настройки можно вызвать также из контекстного меню трея клиентского приложения. В рамках раздела рассматривается вкладка «Аудио».

Среди перечня устройств отображены те из них, модули управления которыми найдены в корневом каталоге клиентского приложения. Существует возможность менять устройства «на лету». Исключение составляет случай, когда ведется разговор. В этом случае необходимо его завершить, и только потом переназначить устройство. Однако система не блокирует переключение в этом случае, но весьма возможна потеря звука.

В окне выбора устройств для всех видов VoIP-модулей доступен выбор кодека. Использование того или иного кодека зависит от инфраструктуры рабочего места. Кодеки серии G.711 обеспечивают наибольшее качество и минимальные затраты на перепаковку, однако объем передаваемых данных при их использовании достаточно велик (64 кБит/с в каждую сторону). В локальной Ethernet сети это не играет большого значения. Кодек MS GSM 0610 существенно снижает трафик и способен работать в более узких каналах данных (13 кБит/сек в каждую сторону), однако производит дополнительную нагрузку на процессор (упаковка звука) и имеет более низкое качество звука по сравнению с G.711. Использование MS GSM 0610 рекомендуется на удаленных клиентских рабочих местах, подключенных через сеть Internet, через узкие, а также через тарифицируемые по трафику каналы передачи данных. Установка кодека влияет как на входящий поток данных, так и на исходящий. При коммутации каналов, у которых установлены различные кодеки, приоритет отдается кодеку с меньшим трафиком.

Выпадающие списки «Динамик» и «Микрофон» позволяют назначать в качестве устройств вывода и ввода звука существующие в системе звуковые устройства.

ВНИМАНИЕ! Категорически не рекомендуется в целях обеспечения стабильности работы приложения менять устройства ввода и вывода звука во время активности устройства (разговора, воспроизведения и т.п.).

Флаг «Использовать DirectX» позволяет изменить способ работы со звуком. Использование DirectSound возможно в случае, если на компьютере установлены библиотеки DirectX версии не ниже 8.

Выбрав в качестве устройства аналоговую гарнитуру, подключаемую к jack разъему звуковой карты, за отсутствием у нее всяческих элементов управления (цифровых кнопок, кнопки снятия трубки / сброса ), модуль телефона приобретает несколько дополнительных кнопок:

· Поднять трубку;
· Положить трубку;
· Завершить;
· Flash;
· Ответить

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

На приведенном №3 изображен вид модуля при активном режиме набора номера после флеш-разрыва и размещения абонента в удержании. Для возврата к абоненту можно нажать кнопку «Отмена», нажать FLASH на телефоне, быстро положить и поднять трубку телефона или положить трубку и дождаться обратного вызова абонента из флеш-буфера.

При выборе гарнитуры в списке доступных устройств, в окне настройки появляется дополнительная вкладка «Гарнитура».

Для jack-гарнитуры доступны параметры автоматического реагирования при поступлении вызова или при поступлении сигнала отбоя. Для их настройки используются соответствующие элементы управления вкладки «Гарнитура».

Также при работе с jack-гарнитурой для набора цифр и управляющих команд можно использовать цифровую часть клавиатуры (NumPad). Для этого в окне выбора устройств необходимо выставить соответствующий флаг. Следует отметить, набор цифр производится только в режиме снятой трубки, а клавиши «+» и «-» на цифровой клавиатуре заменяют собой основные кнопки действий. Поскольку команды взаимоисключены и контекстно-зависимы, кнопка «+» заменяет команды «Поднять трубку», «Завершить / положить трубку» и «Ответить», а кнопка «-» заменяет команду «Flash».

ВНИМАНИЕ! Для включения режима управления гарнитурой с клавиатуры необходимо выставить галку в настройках, проконтролировать отсутствие или отключенное состояние флага в конфигурационном файле клиентского приложения, блокирующего перехват действий клавиатуры, а также включить режим SCROLL LOCK. При активации режима управления любое нажатие кнопки на цифровой клавиатуре будет приводить к соответствующему действию с телефоном вместо стандартных действий в том приложении, которое активно в данный момент (например, «+» будет приводить к снятию трубки или завершению разговора в зависимости от того, какая команда доступна в данный момент). Режим управления активен в любых приложениях и окнах. Для его деактивации достаточно отключить режим SCROLL LOCK. Для набора цифр необходимо также чтобы был включен режим NUM LOCK (автоматически включается вместе с включением SCROLL LOCK).

В режиме активной коммутации у пользователя имеется возможность отключить микрофон своего устройства кнопкой «Выключить звук в панели управления коммутацией модуля «Телефон».

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

Факсимильная передача

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

При отправке в диалоговом окне выбираются файлы изображений, конвертируются при необходимости в правильный формат и после разрыва текущей коммутации начинается передача факсимильного сообщения. В любой момент операцию можно прервать и вновь перейти в разговор, нажав в разделе факсимильной передачи кнопку «Отмена», либо кнопку FLASH на телефоне. Для завершения операции без возвращения в разговор достаточно положить трубку.

Принимая факсимильное сообщение, в диалоговом окне выбирается файл для сохранения изображения в формате *.bmp или *.tiff (в зависимости от типа CTI плат). При получении более чем одного документа сформируется несколько файлов, где к имени выбранного файла будут добавлены строки «_page1», «_page2» и т.д. В любой момент операцию можно прервать и вновь перейти в разговор, нажав в разделе факсимильной передачи кнопку «Отмена», либо кнопку FLASH на телефоне, при этом полученные к этому моменту части документов сохранены не будут. Для корректного сохранения необходимо дождаться полного завершения сеанса. Для прерывания операции без возвращения в разговор достаточно положить трубку.

ВНИМАНИЕ! Уточняйте формат работы факс-модуля в каждом конкретном случае программного и аппаратного обеспечения, так как детали зависят от типа плат, от версии драйвера, а также от версии ПО. Среди зависимых параметров: формат передаваемых страниц, разрешение, способ именования полученных документов, лицензии на факс-сеансы (для плат семейства Ольха-9).

ВНИМАНИЕ! Комплекс Oktell имеет встроенный софт-факс. В зависимости от настроек в модуле «Параметры аппаратуры» будет применяться либо аппаратный факс (применительно к платам), либо встроенный софт-факс.

Передача файлов

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

В режиме коммутации на панели модуля появляется кнопка «Передача документов» с меню, содержащим помимо прочего пункт меню «Отправить файл».

После осуществления выбора одного или нескольких файлов в появившемся диалоговом окне производится их загрузка на сервер. Если размер файла превышает 20 МБ, пользователю выдается дополнительный запрос на подтверждение загрузки с указанием реального размера.

У оппонента пользователя в коммутации полученные файлы сразу будут отображены в поле обмена файлами модуля «Телефон». Сам пользователь также будет иметь возможность обращения с файлами. Файл копируется с сервера в клиентское приложение сразу после закачки, либо при обращении к нему (если производился флеш-разрыв, и файлы передавались в другой коммутации текущей сессии).

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

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

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

В контекстном меню доступны дублирующие команды «Открыть» и «Удалить», а также команда копирования файла в буфер обмена и команда открытия папки с загруженными файлами на клиентском компьютере. В отличие от сервера при завершении цепочки коммутаций файлы не удаляются с клиентского компьютера, очистка производится лишь при перезапуске клиентского приложения.

ВНИМАНИЕ! При необходимости осуществлять закрытую передачу файлов (только между двумя абонентами) можно либо осуществить звонок без дальнейших переводов, либо осуществить удаление файла после приема файла оппонентом, но до флеш-разрыва.

Передача файлов возможна также при внешних звонках с терминалов, работающих под управлением интеграционной библиотеки. Подробнее о режиме передачи данных в разделе «Звонок с терминала» руководства по интеграции, а также в описании SIP-шлюза для приема звонков с терминалов.

У оператора существует возможность прервать затянувшуюся передачу с терминала. Такая потребность может возникнуть при затягивании загрузки (чрезмерно большой файл или слишком узкий канал связи с терминалом). Этому служат пункт контекстного меню «Удалить» и пиктограмма с красным крестом возле имени файла.

Конференц-связь

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

Управляющий - пользователь системы, который имеет монопольный доступ к настройкам конференции. Он производит необходимые изменения свойств, выставляет права последующего доступа к записи конференции, осуществляет приглашения, разрешает или отклоняет запросы на вход в конференцию. Также ему доступно право передать свои обязанности управляющего другому пользователю.

У конференции также есть создатель. Это свойство не подлежит изменению. Создателем является тот пользователь, который инициировал конференцию любым способом (через модуль управления в клиентском интерфейсе или через IVR-сценарий) и задал начальные настройки.

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

Управляющий - свойство селекторного совещания. В конференции его роль выполняет создатель. Создатель может сменить свойства конференции, перевести ее в селекторное совещание и назначить управляющего.

В системе может существовать одновременно произвольное число конференций. С точки зрения коммутаций, каждый канал может одновременно находиться лишь в одной конференции, однако логически пользователь может быть вовлечен в несколько конференций и находиться в них в разных состояниях. Например, нажав FLASH, он может дозвониться до другой открытой конференции. В то же время поступающее приглашение из третьей конференции в этот момент застанет его занятым, но тем не менее сделает участником.

Каждая конференция помимо идентификатора имеет числовой номер, являющийся номером комнаты, в которой происходит конференция. В один момент времени не может существовать двух конференций с одинаковым номером. Указание этого номера дает возможность осуществлять вход в конференцию из сценария IVR. В случае, если конференции с таким номером не существует, и пользователь имеет соответствующие права, установленные в компоненте сценария и в привилегиях, происходит создание новой конференции.

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

Создание и подключение к конференциям.

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

Cоздание конференций в клиентском интерфейсе предполагает предварительную настройку параметров будущей конференции и определение ее участников в списке доступных для приглашения внутренних абонентов системы. Активация режима создания конференции происходит по ссылке «Создать» в модуле управления конференциями (пользователю необходимо право доступа к этому модулю).

Также в клиентском интерфейсе в режиме активной коммутации с абонентом существует возможность преобразовать текущую коммутацию в конференцию. Для осуществления преобразования необходимо нажать кнопку «Конференция» в панели управления коммутацией. Номер комнаты конференции при этом определяется автоматически, а пользователь, активировавший преобразование устанавливается создателем и управляющим конференции.

Создание конференций через сценарии IVR подробно рассмотрено в разделе «Сценарии IVR. Компоненты. Вход в конференцию».

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

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

Подключение к конференции может быть осуществлено несколькими способами.

· Подключение по инициативе пользователя. Любой пользователь, которому доступен модуль управления конференциями, может видеть список активных конференций. В случае, если доступ к конференции не закрыт, у пользователя имеется возможность входа в конференцию щелчком мыши на соответствующей ссылке. Если в конференции настроен вход по разрешению управляющего, то при этом будет произведен запрос. В случае разрешения (или свободного доступа к конференции) на привязанный к рабочему месту телефон поступит вызов из модуля управления конференциями. Канал должен быть свободен, в противном случае приглашение будет положено в его очередь.
· Подключение через сценарий по инициативе абонента. Любой абонент, (как пользователь системы, так и внешний) может осуществить вход в конференцию по своей инициативе (с проверкой прав) через сценарий IVR. Для этого в сценарии IVR существует компонент «Вход в конференцию». Разумеется, логика сценария может быть реализована различным образом. Например, пользователи системы могут иметь внутренний номер, запускающий сценарий IVR, который осуществляет распределение или запрос номера комнаты для подключения к конференции. В то же время внешние абоненты могут подключаться таким образом к конференциям исходя из алгоритма сценария.
· Подключение по инициативе управляющего. Управляющий (или создатель в его отсутствие) в модуле настройки конференции может рассылать приглашения пользователям. В окне выбора участников конференции (вкладка «Участники») отображаются все пользователи системы и их состояния в реальном времени, а также состояния относительно конференции. При отправке приглашения какому-либо пользователю системы ему отсылается уведомление и в очереди канала размещается вызов из конференции. Как только канал получит вызов, пользователь будет введен в конференцию и в его клиентском интерфейсе (в случае наличия) будет отображен состав участников. Если канал недоступен, пользователь автоматически будет выведен из конференции. Управляющему в окне приглашений будет отображено состояние и причина неудачного приглашения.
· Подключение по инициативе участника конференции. Управляющий, создатель и любой другой участник конференции (при соответствующим образом настроенном свойстве конференции) может приглашать других участников с помощью телефона путем размещения конференции во Flash-буфере, соединения с другим абонентом и переключением конференции на него (нажимает FLASH, набирает номер абонента, соединяется с ним, кладет трубку). При наличии у участника конференции клиентского модуля управления в модуле «телефон» будет активна кнопка включения абонента в конференцию, в этом случае не будет необходимости снова осуществлять вход - после ее нажатия оба (и участник и абонент) окажутся в конференции. В общем случае также существует возможность обратного переключения, когда из коммутации с абонентом через Flash-буфер производится переключение его на конференцию.
· Подключение через модули клиентского интерфейса. Из контекстного меню модулей «Сотрудники» и «Мои контакты» управляющий или участник конференции в случае установленного на то разрешения может пригласить в конференцию любого абонента. При этом вызов осуществляется на внутренний номер. В случае, если номер занят, приглашение будет размещено в его очереди. Команда в меню доступна только если пользователь сам находится в конференции.

Настройка конференций при создании и в ходе проведения.

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

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

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

Селекторное совещание.

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

Все абоненты, подключающиеся к селекторному совещанию по умолчанию не имеют права голоса до соответствующего разрешения. При наличии у участника клиентского интерфейса и отсутствия на момент времени права голоса он может выразить свое желание высказаться нажатием кнопки «Хочу сказать». Также произоводится и отмена. Управляющий (а также все участники конференции) увидят мигающую пиктограмму в строчке с именем участника, активировавшего режим.

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

Прослушивание записей.

К информации о прошедших конференциях и к их записям предоставляют доступ модули раздела «Офис»: «Статистика АТС» и «Мои звонки».

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

Видео-звонки

Система Oktell позволяет осуществлять видео-звонки согласно протоколу SIP. Конечные устройства или ПО самостоятельно инициируют активацию видео (INVITE-инструкции SIP), а SIP-сервер Oktell, к которому подключены устройства, осуществляет доставку данных. Так, например, два внешних абонента, работающих в программе X-LITE, могут видеть друг друга, будучи оба подключенными к Oktell. Сервер Oktell поддерживает передачу видео в каскадных подключениях.

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

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

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

Заменить шум на черный фон можно ключом файла конфигурации клиентского приложения ShowVideoNoise со значением 0.

Щелчком мыши на окне предпросмотра производится смена источников. Из окна предпросмотра изображение попадает в основное видео-окно, и наоборот.

Настройка видео

Настройка параметров подключения к видео-камере, а также форматов передачи данных и взаимодействия с сервером производится на вкладке «Видео» окна настройки локальных устройств, вызываемого щелчком мыши на пиктограмме гарнитуры в заголовке модуля «Телефон». Окно настройки локальных устройств можно вызвать также из контекстного меню трея клиентского приложения.

Клиентское приложение Oktell позволяет осуществлять захват изображения с веб и IP камер. В окне настройки производится выбор используемого устройства.

Выбрав из списка типов устройств веб-камеру, необходимо осуществить выбор конкретного устройства в приведенном списке обнаруженных устройств, поддерживающих передачу видео. Подключение к веб-камерам осуществляется через DirectShow. Для корректной работы необходимо, чтобы был установлен DirectX 9 или выше. Кнопка «Настройка web-камеры» открывает серию специальных диалоговых окон по работе с конкретной выбранной веб-камерой.

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

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

В настоящее время клиентским приложением Oktell используется компрессор видео-изображений «Intel H.263 Compressor», который должен быть установлен на компьютере. Отображение окна настройки происходит по нажатию кнопки «Настройка кодека». Качество видео изображения может устанавливаться любое, однако раздел «Advanced Options» должен быть настроен идентично приведенному на изображении.

Разработчиками Oktell в настоящее время ведется работа по унификации работы со всеми возможными вариантами видео-кодеков.

Флаг «Всегда инициировать видео-звонок» определяет режим активации камеры в ответ на активацию видео-сессии оппонентом. При поступлении звонка с внешней линии, у которого уже активна видео-сессия, камера пользователя будет включена сразу после начала коммутации автоматически.


Возможные проблемы и способы их устранения

Сервер не запускается, или запускается долго

· Убедитесь по горящей пиктограмме с зеленым треугольником в трее, что сервер БД Microsoft SQL Server запущен.
· Проверьте настройки в файле конфигурации серверного приложения: «*.exe.config». Имейте в виду, что сервер существует в двух вариантах, и соответственно, файлов конфигурации тоже два.
o Ссылка на базу данных указана верно.
o Логин к БД указан верно.
· Убедитесь в том, что логин указанный в файле конфигурации существует в сервере БД.
· Если сервер запускался до этого, оцените изменения, производимые в настройках системы до перезапуска – правильная ли информация находится в БД о рабочих местах, адресах и серверах.
· Убедитесь в наличии ключа защиты, горит ли на нем светодиод, обнаруживается ли он среди устройств системы. При невозможности корректно использовать USB-порт на сервере, существует возможность удаленного опроса ключа. За подробной информацией обращайтесь в службу технической поддержки.
· Выключите функции энергосбережения USB-концентратора.
· Убедитесь, что установлен Microsoft .NET Framework.
· Если используются многоканальные платы с внутренними линиями – убедитесь в подключении к ним блока питания.
· Убедитесь, что каталог DBAutoUpdate в корне серверного приложения, содержащий обновления для БД, пуст.
· Обратите внимание на лог-журнал исключительных ситуаций серверного приложения, находящихся в каталоге сервера по адресу «Log\Exception\exc_[дата].log». Возможно, в нем будут присутствовать строки, дающие возможность понять причину.
· Убедитесь в указании всех настроек и существовании всех путей для драйверов оборудования.
· Если возникает окно с ошибкой, возможно наличие некорректных значений в файле конфигурации или некорректный его формат.
· Обратитесь в системный лог-журнал операционной системы в поисках ошибок и особых ситуаций.
· Отправьте лог исключений поставщику для решения вашей проблемы с описанием того, что происходило с системой до и во время запуска. Если считаете необходимым, приложите скриншоты экранов.

Клиентское приложение не запускается (не появляется окно авторизации)

· «Программа уже запущена».
o Одновременно на компьютере невозможно запустить более 1 копии приложения в связи с монопольным доступом к драйверам системы.
o В случае использования в терминальном режиме убедитесь в наличии в файле конфигурации клиентского приложения строки «Terminal_Address» и уникальности значения ее ключа.
· Окно с ошибками.
o Убедитесь в наличии Microsoft .NET Framework.
o Убедитесь в наличии всех библиотек приложения.
o Убедитесь в наличии библиотек «DevExpress*.dll».
o Убедитесь в наличии сборок клиентского приложения в серверном каталоге и их корректности.
o При редактировании конфигурационного файла вручную используйте блокнот, иначе возможна потеря в текстовом формате символов, определяющих кодировку, и дальнейшая загрузка будет невозможна без восстановления файла конфигурации.
· Убедитесь, что права текущего пользователя ОС дают возможность работать с файлами и веткой «HKEY_CURRENT_USER» реестра.
· Убедитесь, что текущий пользователь ОС имеет право на полный доступ к папке с установленным клиентским приложением Oktell. Следуйте инструкциям в разделе «Установка клиентского приложения».
· Обратите внимание на лог-журнал исключительных ситуаций запускающего модуля, находящихся в каталоге клиентского приложения по адресу «Log\Starter\str_[дата].log». Возможно, в нем будут присутствовать строки, дающие возможность понять причину.
· Отправьте конфигурационный файл и лог-журналы клиентского приложения за текущий день поставщику для изучения, снабдив описанием (скриншоты, последовательность действий, а также действия, после которых произошло изменение поведения приложения).

Клиент не обнаруживает сервер при авторизации или существенная задержка в откликах

· Посмотрите, правильно ли указаны ссылки на сервер в файле конфигурации клиентского приложения.
· Проверьте сеть, и связь с сервером по адресу из файла конфигурации (командой «PING»).
· В случае установки на сервере более 1 сетевого адаптера, сделайте адаптер, слушающий сеть подключения клиентов первым (Сетевые подключения -> Меню «дополнительно» -> Дополнительные параметры). Если необходимо обеспечить доступ двум сетям, назначьте клиентским компьютерам, не обнаруживающим сервера, дополнительный шлюз с указанием адреса сервера (адрес сетевого интерфейса, обслуживающего сеть, к которой подключен конкретный клиент).
· В файле «<SystemRoot>\System32\Drivers\ETC\hosts» сервера укажите имена и адреса компьютеров сети (в серверный файл внесите информацию об операторском компьютере, а в файл на операторском компьютере внесите информацию о сервере);
· Проверьте подключение на порт 4050 сервера любым доступным способом (например клиент telnet).
· Обратите внимание на лог-журнал исключительных ситуаций клиентского приложения, находящихся в каталоге приложения по адресу «Log\Exception\exc_[дата].log». Возможно, в нем будут присутствовать строки, дающие возможность понять причину.
· Отправьте конфигурационный файл и лог-журналы клиентского приложения за текущий день поставщику для изучения, снабдив описанием (скриншоты, последовательность действий, а также действия, после которых произошло изменение поведения приложения).

После авторизации клиентское приложение не запускается

· Попробуйте зайти под системной записью администратора. Если безуспешно, значит ошибка в базе при установлении свойств в карте. Скорее всего адрес сервера состояний указан неверно. Поправьте ошибку самостоятельно или обратитесь за помощью в техподдержку.
· «Учетная запись системного администратора заблокирована». Сервер состояний запущен, функционирует, и в системе существует по крайней мере один пользователь с ролью администратора. Для решения вопросов зайдите под его учетной записью.
· Убедитесь что в настройках роли пользователя, под учетной записью которого осуществляется авторизация, стоит флаг «Расширенное рабочее место». Иначе система использует его компьютер только для управления аппаратными средствами (например, USB-телефоном).
· «Компьютер не значится в карте». Убедитесь, что компьютер, с которого осуществляется попытка подключения, указан в карте сети, имеет там правильный адрес и подключен к серверу LAN-связью; В карте офиса компьютер должен быть идентифицирован по одному из адресов, выводимых в данном окне непосредственно за текстом. Используйте команду PING в командной строке операционной системы для выявления возможности доступа к адресам.
· Убедитесь в наличии ключа защиты, горит ли на нем светодиод, обнаруживается ли он среди устройств системы.
· Если после авторизации клиентское приложение выдает «Сервер не доступен или находится в состоянии переинициализации», в конфигурационных файлах сервера найдите раздел «ContactServerName» и убедитесь, что в значении установлено «SP_STANDALONE_MODE».
· Обратите внимание на лог-журнал исключительных ситуаций клиентского приложения «Log\Exception\exc_[дата].log».
· Отправьте лог-журналы сервера и клиентского приложения за текущий день поставщику для изучения, снабдив описанием (скриншоты, последовательность действий, а также действия, после которых произошло изменение поведения приложения).

Телефон не издает звуков

· Если аналоговый телефон не издает звуков при поднятии трубки:
o Убедитесь в разделе «Администрирование»
▪ В карте сети телефонный аппарат не соединен логической связью с компьютером;
▪ Если аппарат соединен в карте логической связью с компьютером, убедитесь в модуле «Общие настройки» в разделе «Параметры АТС» в отсутствии флага «Блокировать аналоговую линию при неавторизованном пользователе»;
▪ Если флаг установлен, убедитесь, что на компьютере, управляющем аппаратом, запущено клиентское приложение и авторизован оператор;
o Проверьте подключение телефона к системе.
o Убедитесь в работоспособности телефонного аппарата.
o Попробуйте инициировать звонок на линию.
o Если после перезапуска сервера канал некоторое время работоспособен, проверьте соответствие числа каналов и ограничений в ключе защиты. В случае превышения ограничения система урезает часть каналов из таблиц размещения.
o При использовании плат серии «Ольха 9» убедитесь в работоспособности канала, загрузив тестовое приложение «МА9Т». Для плат серии «Ольха 14» приложение «МА14Т». Для плат «Synway» приложение «text.exe». Соответствующие программы можно среди драйверов к устройству, а также в каталоге дополнительных приложений на диске с дистрибутивом.
o Если после установки комплекса линия всегда находилась в подобном состоянии, убедитесь в наличии канала на плате, проверьте контакты мезонинов.
o Выясните, как обстоит дело с другими линиями аналогичного типа. В конфигурационном файле сервера убедитесь в наличии строк, определяющих запуск серверов оборудования («XX» - порядковый номер сервера):

Сервер плат «Ольха 9»:

<add key="START_SERVER_XX" value="Alder9 Server;oktell.HALAlder9Srv.dll;Alder9;_Loaders\" />

Сервер плат «Ольха 14»:

<add key="START_SERVER_XX" value="Alder14 Server;oktell.HALAlder9Srv.dll;Alder14;_Loaders\" />

Сервер плат «Synway»:

<add key="START_SERVER_XX" value="Synway Server;oktell.HALSynwaySrv.dll;ShCti;" />

Сервер SIP:

<add key="START_SERVER_XX" value="SIP Server;oktell.HALSipSrv.dll;SIP" />

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

· Если USB-телефон (гарнитура) не издает звуков при поднятии трубки:
o Проверьте любой доступный аналоговый телефон на наличие гудка. Если гудка нет, обратитесь к пункту «Если аналоговый телефон не издает звуков при поднятии трубки».
o Выставьте телефон временно как «звуковое устройство по умолчанию» и попытайтесь проиграть какой-нибудь звуковой файл.
o Убедитесь в параметрах громкости телефона как звукового устройства, что громкость на максимуме и звук не выключен.
o Подсоедините вместо этого телефонного аппарата любой другой аналогичный и попробуйте заново.
o Оцените другие рабочие места операторов на подобную проблему.
o Если после перезапуска сервера канал некоторое время работоспособен, проверьте соответствие числа каналов и ограничений в ключе защиты. В случае превышения ограничения система урезает часть каналов из таблиц размещения.
o Изучите настройки брандмауэров.
o Уточните, появилось ли при запуске системы уведомление о регистрации линии.
o Попробуйте нажать кнопку «#» на телефонном аппарате, вызвав тем самым смену сигналов вызова.
o Убедитесь в том, что устройство стоит корректно (USB Audio Device), и драйверы обнаружены и установлены.
o В настройках свойств USB-концентраторов отключите флаг использования режима энергосбережения.
o Проверьте все контакты оборудования, а также проводку на наличии зажимов, перекусов и пр.
o Проверьте настройки адреса и портов для подключения VoIP телефонов. В конфигурационном файле клиентского приложения и настройках соответствующего сервера в модуле «Настройки оборудования».
o Если сервер обслуживает 2 или более сетевых интерфейса, где в каждой из сетей находятся клиентские компьютеры, управляющие VoIP-гарнитурами или телефонами, необходимо настроить для каждого из интерфейсов загрузку своего VoIP-сервера для обеспечения взаимодействия клиентских устройств из разных сетей. Для этого в конфигурационном файле сервера должны быть строчки, содержащие адреса сервера в различных сетях:

<add key="START_SERVER_02" value="Buildin VOIP Server;;Voip;192.168.0.1:5003" />

<add key="START_SERVER_03" value="Buildin VOIP Server;;Voip;10.2.0.1:5003" />

o Если на клиентском компьютере установлено несколько сетевых устройств, то в конфигурационном файле клиента необходимо явно указать по какому из интерфейсов осуществлять посылку и прием пакетов от сервера:

<add key="NETCLIENT_LOCAL_ADDRESS" value="10.2.0.25" />

o Если во время работы отклики от устройства пропадают, оно перестает реагировать на команды сервера – проверьте локальную сеть на прохождение UDP пакетов по установленному порту сигнальной связи. Для анализа с двух сторон (на сервере и на клиенте) установите следящую за трафиком программу, настроенную на конкретный порт и пакеты UDP. В качестве подобной программы может быть использован Ethereal. Дистрибутив можно скачать бесплатно с web-сайта www.ehtereal.com, также он находится в разделе дополнительных программ на диске с дистрибутивом.
o Проверьте сеть на наличие вирусов, сетевых червей и прочих вредоносных программ, увеличивающих трафик, нагрузку на систему, а также изменяющих данные в передаваемых через сеть пакетах.
o Выключите функции энергосбережения сетевого адаптера.
o Если база данных была перенесена на сервер с другого компьютера, пересохраните карту офиса.
o Компьютер находился в спящем или ждущем режиме, вследствие чего сервер разъединил канал связи по таймауту. Перезапустите клиентское приложение.
o Отправьте лог-журналы за текущий день с сервера в техническую поддержку для решения вашей проблемы с подробным описанием и указанием времени наблюдения.

Телефон ведет себя некорректно

· Проверьте другие телефонные аппараты на наличие подобной проблемы.
· Для аналогового телефона
o Убедитесь в отсутствии видимых повреждений в проводке.
o Подсоедините другой (заведомо рабочий) телефонный аппарат на место неисправного.
o Отправьте лог-журналы за текущий день с сервера поставщику для решения вашей проблемы с подробным описанием и указанием времени наблюдения.
· Для USB-телефона
o Убедитесь в отсутствии ошибок при установке устройства.
o В настройках свойств USB-концентраторов отключите флаг использования режима энергосбережения.
o Подсоедините вместо этого телефонного аппарата любой другой аналогичный и попробуйте заново.
o Проверьте все контакты оборудования, а также проводку на наличии зажимов, перекусов и пр.
o Отправьте лог-журналы за текущий день с сервера поставщику для решения вашей проблемы с подробным описанием и указанием времени наблюдения.
· При наличии «обратного звука» (эха той же громкости, что и исходный звук) во время разговора через программный IP-шлюз, проверьте компьютер, использующий гарнитуру и встроенное звуковое устройство.
o Убедитесь, что звук динамиков не доступен микрофону напрямую (стандартное эхо).
o Проверьте звук, подключив к компьютеру любое внешнее звуковое устройство, USB-телефон или USB-гарнитуру.
o Включите проигрывание аудио (на внутренние динамики, наушники и пр.) и одновременно запишите в стандартной звукозаписи операционной системы голос. Если при воспроизведении записанного звука слышится проигрываемый звук – отключите функции микширования «на лету» в свойствах звукового устройства, переустановите драйвер или используйте другое звуковое устройство.
· При торможении звука, щелчках, пропусках
o При наблюдаемых эффектах на USB-телефоне в разговоре с аппаратным каналом платы CTI или наоборот
▪ На сервере производятся длительные и сложные запросы в БД. Вероятно идет построение статистических отчетов или журналов с одного из клиентских мест. Оцените в диспетчере задач загрузку процессора.
▪ На сервере производятся другие действия, существенно загружающие процессор и кэш.
▪ В сети присутствуют вирусы или другие вредоносные программы, блокирующие часть трафика.
▪ Чрезмерная загрузка сети не позволяет всем пакетам быть доставленными.
▪ Звуковое устройство имеет резко отличающуюся скорость воспроизведения/записи. Подключите другой телефон или попробуйте переключить вывод звука на стандартное аудиоустройство (гарнитуру).
o При наблюдаемых эффектах на коммутации двух аппаратных каналов плат CTI
▪ Платы не соединены шиной CTI.
▪ В модуле «Настройки аппаратуры» платы соответствующих каналов находятся в разных группах, что влечет принудительную VoIP-коммутацию. Одновременно большая загрузка процессора (см. предыдущий раздел).
▪ Производится звонок через стороннюю IP-телефонию, вследствие чего звук «портится». Попробуйте перезвонить или найти другой канал соединения с абонентом.
▪ Производится звонок на мобильный телефон, находящийся в зоне плохого приема сигнала.

Низкое качество звука, передающегося между устройствами

· Проверьте формат используемого кодека, возможно понижение качества обусловлено форматом сжатия.
· При низком качестве звука в VoIP канале (при использовании VoIP)
o Проверьте все форматы коммутаций (USB-вш, USB-вн.аналог, USB-USB, аналог-аналог), везде ли наблюдается проблема.
o Проверьте несколько разных каналов, клиентских компьютеров.
o Проверьте файл записи разговора, повторяется ли в нем проблема.
o Проверьте устройство, воспользуйтесь стандартной программой звукозаписи.
o Повторяется ли проблема при использовании другого режима взаимодействия с аудиоустройством (DirectX, WMM).
o При использовании цифровых внешних каналов (E1, SIP) проверьте качество звука при их аппаратной коммутации.
o При наблюдении треска/бульканья в динамике терминального устройства попробуйте увеличить размер JITTER-буфера и MM-буфера (в конфигурационном файле параметры JITTER_DEPTH и WAVE_COUNT соответственно).
o При низкой громкости увеличьте уровень записи микрофона устройства, задействуйте усиление воспроизведения на внешних каналах.
o При использовании ОС WINDOWS VISTA на комьютере пользователя и тресканьи звука в динамике увеличьте значение WAVE_COUNT в конфигурационном файле до 4.
o Оцените загрузку на сервере, хватает ли ресурсов процессора и сети на обслуживание всего потока звонков.
o Убедитесь в отсутствии влияния вирусов, антивирусов, файрволлов в задержке и фильтрации сетевого UDP трафика.
o При использовании удаленных VPN клиентов или клиентов из других сетей попробуйте организовать канал через сервер (параметр в конфигурационном файле OVER_SERVER).
o Включите полное логирование: при проблемах на стороне сервера в настройках аппаратуры включите все виды трассировок, при проблемах на стороне клиента в конфигурационном файле выставьте значение 15 параметра TRACE_HARDWARE. Произведите звонок и отправьте журналы в тех.поддержку.

· При низком качестве звука в аппаратных коммутациях (между каналами плат)
o При плохой слышимости (громкости) попробуйте настроить соответствующие значения в параметрах аппаратуры или вспомогательных программах. При отсутствии эффекта попробуйте добиться хорошей слышимости в тестовых программах.
o Убедитесь, что при коммутации не используется VoIP технология, платы-владельцы соединяемых каналов соединены шиной и находятся в одной группе в настройках аппаратуры.
o Проверьте терминальные устройства, соедините их через другие каналы или непосредственно.
o Проверьте внешнюю линию, соедините ее непосредственно с терминальным устройством.

Клиентское приложение работает нестандартно

· Если после запуска клиентского приложения вы видите в левом нижнем углу панели состояния текст «Информация недоступна». В этом случае по определенным причинам сервер не может создать канал обратной связи с компьютером-клиентом. Возможными причинами могут быть:
o Серверное и клиентское приложения разделены в сети прокси-сервером.
o Клиентское приложение запущено под пользователем операционной системы с ограниченными правами на доступ и использование ресурсов системы.
o Ошибки, занесенные в конфигурационные файлы. Несоответствие портов, нарушение свойств каналов и пр.
o Различие версий клиентского и серверного приложений.
· Если при управлении VoIP-устройством (USB-телефоном или гарнитурой) обнаруживается зацикливание процессов обнаружения и потери устройства, возможно это связано с большой загрузкой процессора. В качестве варианта можно использовать перенос управляющего модуля в общий процесс приложения (по умолчанию это отдельный процесс «PhoneHost»). Для этого в конфигурационном файле клиентского приложения необходимо поместить параметр (или изменить значение существующего):

<add key="SEPARATE_PROCESS" value="0" />

· Если после автоматического перезапуска клиентского приложения возникают проблемы, установите режим перезапуска с выгрузкой процесса (параметр в конфигурационном файле RestartApplicationWithProcess)
· Отправьте лог-журналы за текущий день с сервера и клиентского компьютера поставщику для решения вашей проблемы с подробным описанием и указанием времени наблюдения.

Сервер «тормозит»

· Включите лог-журнал служб АТС и проверьте его на зацикливание сценариев, убедитесь в корректности последнего форматированного сценария.
· Убедитесь, что параметры сервера соответствуют рекомендованным для использования совместно с VoIP-шлюзом.
· Убедитесь, что число VoIP-коммутаций соответствует норме и параметрам сервера; Возможно аппаратные каналы CTI также коммутируются через шлюз (если платы не объединены CT-bus и/или в настройках аппаратуры установлены разные индексы групп для плат).
· Попробуйте деактивировать все задачи, перезапустить сервер и оценить наличие проблемы.
· Убедитесь в отсутствии задач с большими списками, работающими через кэш в ОЗУ.
· Убедитесь в производительности БД, нагрузке на БД, жесткие диски.
· Попробуйте определить действие, повлекшее возникновение проблемы и отменить его.
· Отправьте лог-журналы за текущий день с сервера поставщику для решения вашей проблемы с подробным описанием и указанием времени наблюдения.

Невозможно осуществить исходящий городской звонок через «9»

· После набора «9» система не выдает сигнала
o Проверьте существование служебного номера «Выход в город».
o Убедитесь, что устройство функционирует нормально.
· После набора «9» система выдает сигнал «Занято»
o Для текущего пользователя не назначены права на исходящие звонки или не установлен порядок выделения внешних линий (модуль «Администрирование. Права»).
o Разрешенные для совершения звонка внешние линии выключены, запрещены для совершения исходящих или отмечены как подсоединенные к офисной АТС (модуль «Администрирование. Линии»).
o Убедитесь, что внешние линии свободны и доступны (модуль «Администрирование. Мониторинг. Линии»).
· После набора «9» и номера система не реагирует и звонка не происходит
o В модуле «Мониторинг линий» убедитесь что внешняя линия выделяется и в нее производится набор.
o В случае использования (выделения) цифровых внешних линий (Е1 или SIP) необходима команда посылки номера в линию. В мониторинге линий проверьте тип выделяемой линии. Убедитесь что в общих настройках заданы и включены режимы отправки номера в цифровую линию. Убедитесь, что значения корректны и используются.
o В свойствах выделяемой линии проверьте наличие префикса набора. Убедитесь в корректности значения.

Прочие возможные проблемы

· При работе с датами происходит некорректное преобразование из строкового типа. Это может случиться если в ОС или MS SQL Server установлены нестандартные способы представления формата Дата/время. В качестве одного из решений можно использовать ручную настройку формата дат в конфигурационном файле сервера. Необходимо найти там строки с масками преобразования даты в строку и изменить их надлежащим образом. Через конфигурационный файл можно задать 3 различных формата. Попытки их применения будут осуществляться в порядке следования.

<add key="Default_DateTime_Format1" value="dd.MM.yy HH:mm:ss" />

· Если при запуске сервера (при перезагрузке) возникает ошибка использования портов. Выгрузите приложение, подождите несколько секунд (20-30) для освобождения операционной системой портов и вновь запустите приложение. Также можно после выгрузки приложения на время отключить сеть или вынуть сетевой кабель.


Структура пространственной БД

Вся статистика работы в call-центре попадает в пространственную БД «oktell_cc_temp». Все отчеты, касающиеся работы Call-центра строятся на основе лежащей в ней информации. Подробнее об отчетах см. разделы «Call-center. Статистика» и «Call-center. Индикаторы».

Три пространственных таблицы:

A_Cube_CC_EffortConnections – информация о коммутациях в call-центре и попытках дозвона.

A_Cube_CC_OperatorStates – информация о состояниях операторов в call-центре.

A_Cube_CC_CallQueue – информация о состояниях и нагрузках очередей входящих задач.

А также таблицы с категориями:

A_Cube_CC_Cat_OperatorInfo – информация об операторах.

A_Cube_CC_Cat_OperatorStateTypes – информация об используемых состояниях операторов.

A_Cube_CC_Cat_Project – информация о проектах.

A_Cube_CC_Cat_Task – информация о задачах.

A_Cube_CC_Cat_TaskResultTypes – информация о результатах совершения звонков.

Для построения основных отчетов информация берется из пространственных таблиц, а при построении итоговой выборки по идентификаторам происходит пересечение с таблицами категорий для получения адекватных для восприятия показателей (названий, имен, описаний)

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

Прочие касающиеся языка SQL темы находятся вне рамок руководства.

Ниже приводятся поля основных таблиц.

A_Cube_CC_EffortConnections

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

[IdProject] [uniqueidentifier]

Id проекта совершенного звонка или попытки совершения звонка. Пересечение с таблицей A_Cube_CC_Cat_Project.

[IdTask] [uniqueidentifier]

Id задачи. Пересечение с таблицей A_Cube_CC_Cat_Task.

[IsOutput] [bit]

Флаг-признак исходящей задачи.

[IdEffort] [uniqueidentifier]

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

[IdOperator] [uniqueidentifier]

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

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

[IdInList] [int]

Код абонента в списке, прикрепленном к задаче.

[AbonentNumber] [nvarchar] (20)

Номер абонента, по которому производился дозвон (исх. задача), или с которого производился звонок (вх. задача).

[CallResult] [int]

Результат звонка. Пересечение с таблицей A_Cube_CC_Cat_TaskResultTypes.

[CallResultInfo] [nvarchar] (100)

Описание результата (если было назначено).

[DateTimeStart] [datetime]

Дата и время начала звонка.

[DateStart] [datetime]

Дата начала звонка с нулевым временем.

[TimeStart] [datetime]

Время начала звонка с нулевой датой.

[DateTimeStop] [datetime]

Дата и время окончания звонка.

[IdConn] [uniqueidentifier]

Id коммутации. В контексте одного звонка при переключении оператором звонка на другого оператора или в IVR каждая коммутация имеет отдельную запись в таблице. Может быть не заполнено (is NULL).

[IdChain] [uniqueidentifier]

Id звонка (цепочки коммутаций). Одинаково для всех коммутаций, в контексте одного звонка. Может быть не заполнено (is NULL).

[IdAUser] [uniqueidentifier]

Id звонящего абонента. Может быть не заполнено (is NULL).

[IdBUser] [uniqueidentifier]

Id принимающего звонок абонента. Может быть не заполнено (is NULL).

[IdExtLine] [uniqueidentifier]

Id внешней линии, по которой происходит реализация звонка.

[LenTime] [float]

Длительность коммутации в секундах.

[LenQueue] [float]

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

[IsBetweenOp] [bit]

Флаг коммутации, когда разговор происходит между двумя операторами, абонент находится во Flash-буфере. Может быть не заполнено (is NULL).

[OpponentInfo] [nvarchar] (100)

Информация об абоненте.

[IsHandled] [bit]

Флаг обработанного звонка. 0, когда коммутации не произошло.

[IsSuccess] [bit]

Флаг успешной обработки. Подробно см. раздел «Call-центр. Сценарии. Сценарии диалога. Стоп-форма».

[IsRecorded] [bit]

Флаг наличия файлов с записью разговора. Может быть не заполнено (is NULL).

[IdRecDir] [int]

Id каталога, в который происходит запись. Пересечение с таблицей основной БД A_Stat_RecordDirectories. Может быть не заполнено (is NULL).

[ALineNum] [nvarchar] (5)

Код линии, совершающей звонок.

[BLineNum] [nvarchar] (5)

Код линии, принимающей звонок.

[UserResult] [int]

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

Пересечение с таблицей из основной БД A_TaskManager_CubeUserResults. Подробно см. раздел «Call-центр. Сценарии. Сценарии диалога. Стоп-форма».

A_Cube_CC_OperatorStates

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

· Предварительная обработка
· Ожидание ответа абонента
· Обратный вызов
· Разговор с абонентом
· Разговор между операторами
· Разговор по задаче
· Поствызывная обработка
· Прочие разговоры
· Перерыв
· Готов

Перечисленные состояния относятся только ко времени пребывания оператора в режиме Call-центр.

[Id] [int] | Целочисленный идентификатор для служебного пользования.
[IdTask] [uniqueidentifier] | Id задачи, в контексте которой оператор находился в данном состоянии. Пересечение с таблицей A_Cube_CC_Cat_Task. Может быть не заполнено (is NULL), если состояние не является участием в задаче.
[IsOutput] [bit] | Флаг-признак исходящей задачи. Может быть не заполнено (is NULL), если состояние не является участием в задаче.
[IdOperator] [uniqueidentifier] | Id оператора. Пересечение с таблицей A_Cube_CC_Cat_OperatorInfo.
[CallResult] [int] | Результат звонка, в ходе которого оператор находился в данном состоянии. Пересечение с таблицей A_Cube_CC_Cat_TaskResultTypes. Может быть не заполнено (is NULL), если состояние не является участием в задаче.
[State] [int] | Состояние оператора. Пересечение с таблицей A_Cube_CC_Cat_OperatorStateTypes.
[DateTimeStart] [datetime] | Дата и время начала пребывания в данном состоянии.
[DateStart] [datetime] | Дата начала пребывания в данном состоянии. Время нулевое.
[TimeStart] [datetime] | Время начала пребывания в данном состоянии Дата нулевая.
[DateTimeStop] [datetime] | Дата и время окончания пребывания в данном состоянии.
[LenTime] [float] | Длительность в секундах пребывания в данном состоянии.

A_Cube_CC_CallQueue

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

[Id] [int] | Целочисленный идентификатор для служебного пользования.
[IdTask] [uniqueidentifier] | Id задачи, чья очередь содержится в записи.
[IdProject] [uniqueidentifier] | Id проекта задачи.
[DateTimeStart] [datetime] | Дата и время начала периода с неизменяемыми количественными значениями.
[DateStart] [datetime] | Дата начала периода, время нулевое.
[TimeStart] [datetime] | Время начала периода, дата нулевая.
[DateTimeStop] [datetime] | Дата и время окончания периода. У последней внесенной записи по задаче всегда пусто (is NULL).
[CountQueue] [int] | Количество абонентов, находящихся в очереди в текущем периоде
[CountOperator] [int] | Количество операторов, обслуживающих задачу, активных в текущем периоде.
[CountTalking] [int] | Количество ведущихся по задаче разговоров в текущем периоде. При ненулевой очереди отличается от общего числа активных операторов на число операторов, занятых в других задачах.
[elt1WaitStart] [datetime] | Дата и время начала ожидания первого абонента в очереди.
[elt1WaitSec] [int] | Время в секундах, прошедшее с начала ожидания первого абонента в очереди.

В таблицах категорий для пользования отведены два поля: [Id] и [Name]. В зависимости от типа данных [Id] принимает значения int или uniqueidentifier.


Порты, используемые системой

Системой Oktell при формировании сетевого трафика используется ряд зарезервированных портов. Для подключения клиентского приложения к серверу используется порт 4050. Для связи серверов используется порт 4051. Для связи логического сервера и сервера аппаратуры используется порт 4052. При использовании встроенного VoIP-сервера связь клиент-сервер на аппаратном уровне происходит с использованием портов 4003-4005. Диапазон портов для обмена голосовым трафиком между компьютерами: 4100-4199.

Информация о портах необходима при настройке брандмауэров, антивирусов, прокси-серверов и при использовании прочих внешних следящих программ.

Приведенные выше настройки для портов являются «используемыми по умолчанию», однако при различных конфликтах система позволяет задать порты в ручном режиме. Вся информация содержится в конфигурационных файлах приложений. На клиенте: oktell.ClientStarter.exe.config, на сервере два идентичных файла конфигурации оконного приложения и службы: oktell.ServerForm.exe.config и oktell.ServerService.exe.config.

ВНИМАНИЕ! При изменении портов не забывайте одновременно изменять настройки серверного и клиентского приложений. Используйте полнотекстовый поиск по файлу, чтобы удостовериться в полноценной замене.

ВНИМАНИЕ! При редактировании конфигурационного файла используйте блокнот, иначе возможна потеря в текстовом формате символов, определяющих кодировку, и дальнейшая загрузка будет невозможна без восстановления файла конфигурации.


Параметры файлов конфигурации

Ряд настроек комплекса хранится в файлах конфигурации соответствующих приложений. Файл конфигурации загружается однократно в момент запуска приложения, и хранящиеся в нем настройки не могут быть изменены в ходе работы. Любые изменения файлов конфигурации применяются только при следующем запуске соответствующего приложения.

Настройки файла конфигурации клиентского приложения влияют на работу только конкретного клиента.

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

Файл конфигурации клиентского приложения: oktell.ClientStarter.exe.config

Файл конфигурации серверной службы: oktell.ServerService.exe.config

Файл конфигурации серверного приложения: oktell.ServerForm.exe.config

Изменять файлы необходимо в редакторах, не изменяющих кодировку (рекомендуется стандартный редактор «Блокнот»). Такие редакторы как «Microsoft Word» и «Wordpad» сбивают кодировку, в следствие чего запуск приложения системы становится невозможным. При попытке запуска с некорректным конфигурационном файлом возникает системное окно с описанием ошибки.

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

Формат представляет собой стандартный XML-документ со специфическими элементами. Допустимые настройки находятся в разделе между тегами <appSettings> и </appSettings>. Каждый конкретный параметр представляет собой строку

<add key="KEY_STRING" value="VALUE_STRING" />

где KEY_STRING - название параметра, VALUE_STRING - значение параметра. Комментарии располагаются между строками <!-- и -->.

Параметры файла конфигурации серверного приложения.

Language. Определяет языковую схему, используемую комплексом. В основном каталоге приложения находятся файлы Lang*.xml, представляющие собой наборы текстов для отображения в клиентских интерфейсах и БД. Для выбора того или иного языка необходимо в качестве значения данного параметра выставить соответствующее расширение имени файла (*). Например для использования файла LangRus.xml необходимо прописать значение «rus».

Язык по умолчанию – русский (применяется, если в конфигурационном файле не указан язык, или если не найден файл указанного языка).

Русский также является базовым языком. То есть если какого-либо кода не найдено в файле языка, то в альтернативу будет применен русский текст, заданный в коде программы. Язык также определяется в конфигурационном файле клиентского приложения, но после подключения к серверу клиентское приложение синхронизирует язык с установленным на сервере.

HALSeparate. Режим запуска модуля поддержки оборудования. 0 - в текущем процессе, 1 - в отдельном процессе. В случае, если оборудование в некоторых случаях вызывает критические ошибки, подгрузка модуля поддержки оборудования в отдельном процессе позволяет не терять основной работоспособности сервера. В моменты падения процесса основная служба перезапускает его, производит фоновую регистрацию и продолжает работу.

В момент перерегистрации все линии переходят в состояние «Отключена», пользователи переходят в состояние «Без телефона», все коммутации разрываются, логика резервирований очищается. Менеджер задач реагирует способом, аналогичным тому случаю, когда абоненты на внешних линиях положили трубки. Возможно файлы записей оборвавшихся разговоров будут иметь некорректный заголовок, что сделает невозможным их прослушивание стандартными средствами. Полностью процесс переинициализации занимает 5-10 секунд.

START_SERVER. Индексированные параметры, определяющие запускаемые серверы аппаратуры. Доступные серверы: Сервер CTI плат Ольха-9, Сервер CTI плат Ольха-14, сервер CTI плат Synway, сервер SIP, серверы VoIP телефонии. При установке системы параметры выставляются согласно выбранным в дистрибутиве значениям. Однако в сложных системах могут потребоваться модификации. Например, в случае если происходит замена типа платы на рабочей системе, использование нескольких разных типов плат, а также при запуске нескольких VoIP серверов, обслуживающих разные подсети. Загрузке подлежат серверы с индексами от 1 до 32 (в примере - часть строки XX).

Сервер плат «Ольха 9», «Ольха 14»:

<add key="START_SERVER_XX" value="Alder9 Server;oktell.HALAlder9Srv.dll;Alder9;_Loaders\" />

<add key="START_SERVER_XX" value="Alder14 Server;oktell.HALAlder9Srv.dll;Alder14;_Loaders\" />

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

Сервер плат «Synway»:

<add key="START_SERVER_XX" value="Synway Server;oktell.HALSynwaySrv.dll;ShCti;" />

Сервер плат «Yeastar E1»:

<add key="START_SERVER_XX" value="E1 Yeastar Server;oktell.HALYeastarSrv.dll;YeaCti;" />

Сервер SIP:

<add key="START_SERVER_XX" value="SIP Server;oktell.HALSipSrv.dll;SIP;sip:*:5060" />

Последний элемент строки после точки с запятой устанавливает детальные настройки сетевого интерфейса и порта, на которых запускаемый SIP-сервер будет активен. По умолчанию «sip:*:5060», то есть сервер слушает все интерфейсы на порте 5060. При необходимости установить какой-либо конкретный интерфейс необходимо вместо «*» указать его адрес.

Серверы VoIP:

<add key="START_SERVER_XX" value="Buildin VOIP Server;;Voip;localhost:4003" />

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

Сервер виртуальных каналов

<add key="START_SERVER_XX" value="Virtual Server;oktell.HALVirtualSrv.dll;VS;12/10" />

Последний элемент строки указывает количество используемых каналов - внешних/внутренних.

MASTER_BOARD. При использовании плат семейства Ольха может потребоваться указание мастер-платы, от которой происходит синхронизация потока Е1. В этом случае параметр необходимо раскомментировать и указать номер мастер-платы, начиная с 0 в порядке их определения драйвером в системе. По умолчанию параметр закомментирован и используется значение по умолчанию 0.

USE_CT-BUS_BOARDx. При использовании плат семейства Ольха может потребоваться принудительное отключение CTBUS на одной или нескольких платах (например в случае, если шлейф шины охватывает менее установленного количества плат). Индексированный параметр, где вместо X ставится номер платы начиная с 0 в порядке определения системой, со значением 0 отключает использование CTBUS на плате. По умолчанию все платы используют шину CTBUS при ее наличии.

VOIP_PORT_START. Начальный порт для обмена голосовым трафиком через сервер VoIP телефонии.

VOIP_PORT_END. Конечный порт для обмена голосовым трафиком через сервер VoIP телефонии.

USE_AFFINITY_MASK. «1» - использовать разделение задач по процессорам. Половина процессоров для сервера логики, другая половина для сервера HAL. «0» - значение по умолчанию. В этом случае операционная система самостоятельно занимается распределением.

JITTER_DEPTH. Значение глубины джиттер-буфера на сервере. Минимальное значение - «4», по умолчанию - «4». При увеличении значения происходит рост задержки в голосовом обмене по направлению звука к серверу, эффективнее исключая влияние проблем сети.

TIMER_TYPE. Тип используемого таймера тактирования звуковых пакетов. На разных операционных системах и компьютерах различные варианты таймеров могут иметь достаточно сильную погрешность, влияющую на итоговое качество звука.

Возможные значения:

0 - Системный таймер по умолчанию. Дает более точное тактирование по сравнению с таймером на ожидании. Выдает точное тактирование в Windows Vista и некоторую погрешность в предыдущих версиях Windows. Система буферизации звука в этом случае сглаживает разброс, однако существуют компьютеры, где погрешность таймера постоянна. Это влечет пропуск пакетов и заметное ухудшение итогового качества звука. На таких компьютерах необходимо использовать другие типы таймеров. Рекомендуется мультимедийный.

1 - Системный таймер в собственном потоке приложения.

2 - Имплементация таймера в потоке с использованием функции WaitForSingleObject().

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

По умолчанию «0».

TIMER_HIGHRES. Тип используемого счетчика интервалов времени. «0» - миллисекундный системный счетчик GetTickCount, «1» - Query Performance Counter. По умолчанию «0».

ProcessPriority. Приоритет серверного процесса. По умолчанию «0» - Нормальный. «1» - выше среднего, «2» - высокий, «3» - реального времени.

DBServerName. Адрес сервера, на котором находится база данных MSSQL. По умолчанию «(local)».

DBName. Имя базы данных, к которой производится подключение. По умолчанию «oktell».

DBLogin. Имя пользователя, учетной записью которого пользуется система. По умолчанию «AutelService».

DBInstanceName. Имя экземпляра сервера MSSQL. По умолчанию «MSSQLSERVER». Для доступа к службе, обеспечивающей работу БД. В момент запуска службы Oktell осуществляется проверка доступности БД. Если SQLServer, обслуживающий БД коммуникационного сервера, находится на том же компьютере, что и служба Oktell, то при невозможности обращения к БД Oktell проверяет и перезапускает локальную службу SQLServer (указанный instance).

Если работа SQLServer осуществляется на другом компьютере, то во избежании запуска службы SQLServer на локальной машине в значение поля можно поставить «0». Октелл будет осуществлять бесконечное ожидание корректного подключения к БД перед началом загрузки, а сервер баз данных не будет загружать в ОЗУ свои данные, тем самым коммуникационный сервер будет гарантирован от кэширования данных на диск, и, как следствие, временных приостановок операционной системой работы всех служб и приложений в ожидании завершения операции, что достаточно критично при активных коммутациях.

DBConnectionString. Строка подключения, задаваемая явно. Используется при настройке подключения к службам SQL с индивидуальными параметрами, при которых не подходят параметры по умолчанию. При отсуствии этого свойства, или пустом его значении, подставляется строка:

"server=(local);database=oktell;uid=AutelService;pwd=[pwd];pooling=false",

где значения параметров server, database и uid подставляются из вышеописанных свойств. При явном указании строки подключения пароль может быть указан явно, либо использована последовательность символов «[pwd]», указывающая системе на необходимость подстановки пароля для логина AutelService.

DBTransactionLogSize_1, DBTransactionLogSize_2. Размеры транзакционных лог-файлов баз данных - основной и пространственной. По умолчанию по 500 МБ.

RepUpdateDir. Каталог с обновлениями отчетов call-центра.

DBUpdateDir. Каталог с обновлениями для БД.

DBUpdateDirExtern. Каталог с внешними обновлениями для БД. Расположенные здесь файлы с текстом, представляющим собой один совокупность нескольких SQL-batch, исполняются в БД по очередности их имен в момент запуска сервера. После успешного исполнения файлы удаляются. В случае возникновения ошибок их описание можно обнаружить в лог-журнале Exception.

ContactServerName. Тип подключения к драйверу ключа по умолчанию. В случае невозможности осуществляется перебор всех возможных вариантов.

ShowServerLogAtStartUp. При использовании серверного приложения «1» включает трассировку служебного лог-журнала в окно приложения.

LicenseMode. Текущий режим лицензирования. По умолчанию «1» - использование файла сертификата.

Default_DateTime_Format. Индексированные параметры, определяющие нестандартныей варианты преобразования типа СТРОКА к типу ДАТАВРЕМЯ. Используются строки с индексами от 0 до 99, перебор в ходе работы осуществляется в порядке увеличения индексов.

SkipCloseMutexCommand. Режим автоматического закрытия сервера через мьютекс-команду необходим в целях исключения проблем с операциями обнаружения процессов. Встречаются системы, в которых отключены или недееспособны службы, необходимые для обнаружения внешнего процесса. В этом случае процесс копира не в состоянии при необходимости остановить серверный процесс перед обновлением и/или для перезапуска. «1» - пропускать команду закрытия, отданную через системные мьютексы процессом копира. «0» и другие значения - команда будет распознаваться и сервер будет реагировать на нее автоматическим закрытием.

Раздел LOG.

Хранит настройки лог-сервера комплекса. Среди неописываемых настроек - пути к папкам для сбора журналов.

LOG_storedays. Длительность хранения лог-журналов в днях. По умолчанию «7». По истечении указанного периода журналы удаляются системой. В некоторых случаях объем журналов может достигать нескольких гигабайтов за день.

LOG_root. Абсолютный или относительный путь к папке с лог-журналами. По умолчанию «Log», то есть относительный путь в каталоге серверной службы/приложения.

Раздел DEBUGGING.

Хранит настройки, согласно которым ведется заполнение служебного сервисного лог-журнала. По умолчанию все параметры выставлены в «1», что влечет полное логирование служб сервера. Полное или частичное отключение уменьшает размер журнала, однако не даст информации в случае возникновения сбоев и общением с технической поддержкой.

Раздел KEYREMOTE.

Хранит настройки для подключения к внешнему серверу, управляющему ключом защиты. Необходимо в редких случаях, если USB-порт на сервере не функционирует должным образом.

Параметры файла конфигурации клиентского приложения.

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

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

LogicServerAddress. Адрес для подключения к серверу логики.

LogicServerPort. Порт для подключения к серверу логики.

NETCLIENT_SERVER_ADDRESS. Адрес для подключения к серверу аппаратуры.

NETCLIENT_SERVER_PORT. Порт для подключения к серверу аппаратуры.

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

NETCLIENT_LOCAL_PORT. Локальный порт для обмена сигнальным трафиком по UDP.

NETCLIENT_VOICE_PORT. Локальный порт для обмена голосовым трафиком по UDP.

ВНИМАНИЕ! Вышеперечисленные параметры определяют различные адреса и порты для организации сетевого канала подключения к серверу. Эти параметры могут присутствовать в конфигурационном файле несколько раз с добавлением к концу строки-ключа разных целочисленных индексов. Например NetConnectionName_1 и NetConnectionName_2. Индекс 0 не указывается, вместо него используется значение без индекса. В случае указания в конфигурационном файле нескольких подключений в окне авторизации будет отображен список их имен и доступен выбор одного из них. Это удобно использовать при работе с несколькими серверами с одних и тех же клиентских рабочих станций.

AutoUpdate. «1» - обновлять клиента автоматически. «0» - не обновлять автоматически при запуске, если обнаружено отличие версий. По умолчанию «1». Настоятельно не рекомендуется оставлять рабочую версию программы со значением «0» и использовать этот режим только для отладочных целей.

AutoUpdateGateway. «1» - обновлять шлюз автоматически. «0» - не трогать. По умолчанию «0». В список шлюзов требуется добавить адрес сервера, если подключение производится к серверу с несколькими сетевыми интерфейсами через интерфейс с индексом более 1.

TerminalAddress. Строка, определяющая уникальный адрес клиентского места. Приписывается ко всем адресам компьютера для определения клиентского места в карте офиса (например «FUTURAMA/terminal1»). Именно эту строку необходимо будет указать в карте офиса для идентификации. Решает проблему терминальных подключений, где все клиенты физически запускаются с одного компьютера. По умолчанию «».

TimeSynchronization. «1» - синхронизировать время с сервером при запуске, «0» - не синхронизировать. По умолчанию «1».

RestartApplicationWithProcess. «1» - любой перезапуск клиента производится с выгрузкой процесса. «0» - выгрузка процесса производится только для применения обновлений, другие перезапуски осуществляются внутри процесса. По умолчанию «0».

ProcessPriority. Приоритет процесса клиентского приложения и процесса обслуживания внешних звуковых устройств. «0» - нормальный, «1» - выше среднего, «2» - высокий, «3» - реального времени. По умолчанию «1».

HAL_skip_loading. «1» - пропускать загрузку модуля обслуживания устройств работы со звуком. «0» - нормальный режим.

Register_ocx. «1» - регистрировать библиотеки обслуживаемых устройств перед запуском, «0» - не регистрировать. По умолчанию «1».

TRACE_HARDWARE. Уровень трассировки аппаратного модуля. Битовая маска xxxx. C конца: 0 - TraceCall, 1-TraceEvents, 2-TraceVoice, 3-TraceNet. По умолчанию «1». Для полной трассировки значение «15».

SEPARATE_PROCESS. «1» - запускать отдельный процесс для работы с устройствами. «0» - работать с устройствами в собственном процессе. По умолчанию «1».

JITTER_DEPTH. Значение глубины джиттер-буфера на клиенте. Минимальное значение - «4», по умолчанию - «4». При увеличении значения происходит рост задержки в голосовом обмене по направлению звука в клиентское устройство, эффективнее исключая влияние проблем сети.

WAVE_COUNT. Значение глубины буфера обмена звука. Минимальное значение - «2», по умолчанию - «2». При увеличении значения происходит рост задержки в голосовом обмене по направлению звука в клиентское устройство, эффективнее исключая влияние проблем звукового устройства.

OVER_SERVER. «1» - обмен трафиком через сервер. «0» - обмен трафиком по возможности напрямую. По умолчанию «0».

WRITE_VOICE. Отладочный параметр для оценки звукового потока на входе в клиентский HAL из сети до воспроизведения непосредственно в устройстве. «1» - отладочная запись в файл включена, файл с именем, соответствующим текущему времени размещается в корне клиентского приложения . «0» - отладочная запись отключена. По умолчанию «0».

WAVEIN_AUTOCLOSE. «1» - закрывать устройство ввода звука после завершения коммутации. «0» - оставлять открытым. По умолчанию «0».

USE_DIRECTSOUND. Тип работы со звуком по умолчанию. Выбирается в клиентском интерфейсе. «1» - использовать для работы со звуком библиотеки DirectSound. «0» - обычный режим через системные функции Windows Multimedia (WMM). По умолчанию «0».

NETCLIENT_PAYLOAD. Кодек по умолчанию для обмена голосовым трафиком. Выбирается в клиентском интерфейсе. Здесь служит для задания начальной настройки. 0 - 711mulaw, 8 - 711alaw, 41 - gsm610. По умолчанию «8».

PHONEDEVICE_WAVEOUT. Устройство вывода звука (спикер) по умолчанию. Выбирается в клиентском интерфейсе. Здесь служит для задания начальной настройки.

PHONEDEVICE_WAVEIN. Устройство ввода звука (микрофон) по умолчанию. Выбирается в клиентском интерфейсе. Здесь служит для задания начальной настройки.

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

SIGNAL_VOLUME. 0-100. Уровень громкости генерируемых в локальное устройство системных звуков и тонов. По умолчанию 50.

UseKeyHook. Параметр позволяет принудительно отключить режим перехвата действий клавиатуры для управления гарнитурой. Отключение может понадобиться при обнаружении проблем и конфликтов с операционной системой. «1» - режим перехвата активирован. «0» - режим перехвата деактивирован. По умолчанию «1». Выключение требуется на 64 разрядных ОС.

WatcherResourceLogType. Формат логирования ресурсов. С помощью параметра можно настроить вывод в клиентский лог-журнал WATCHER информации по использованию процессом ресурсов системы. Объем используемой памяти, количество открытых дескрипторов, количество потоков, пользовательские системные ресурсы, ориентировочное среднее процессорное время по всему процессу и отдельно по всем его потокам. 0 - не логировать, 1 - информация о процессе каждую секунду, 2 - информация о процессе и активным потокам каждую секунду, 3 - информация о процессе и всем его потокам каждую секунду, 4 - информация о процессе каждую минуту. По умолчанию 4.

RestoreLastModules. «1» - осуществляет при загрузке приложения загрузку и восстановление модулей, активных перед закрытием программы. «0» - запускает приложение с пустым фоном без дополнительной загрузки модулей; это экономит время на загрузке, так как некоторые модули требуют достаточно длительного времени для полной загрузки, однако пользователь при необходимости сам может активировать модуль по стандартной схеме из главного меню. По умолчанию «1».

ShowVideoNoise. «1» - в видео-окне модуля ТЕЛЕФОН при отсутствии видео-сигнала отображается черно-белый шум, «0» - черное окно. По умолчанию «1».

Memory_UseSameDialogForms. «1» - активирует режим использования одних и тех же окон в режиме операторских диалоговых форм без уничтожения и создания при каждом показе. Используется на компьютерах с минимальным объемом оперативной памяти во избежание скачкообразного роста используемой памяти. «0» - деактивирует режим. По умолчанию «0».

Debug_PingErrorRestart. «0» - отключает автоматическую перезагрузку клиентского приложения при отсутствии откликов сервера на команды Ping. Используется для отладочных режимов, в основном при отладке plugin-программ. «1» - обычный режим. По умолчанию «1».

PingTimeoutNotify. Устанавливает период в миллисекундах, при превышении которого в момент вызова метода Ping возникает уведомление о плохой связи с сервером.

ActivationServer. Ссылка на сайт активаций для режима автоматической активации тестовой версии. По умолчанию «http://activate.telsystems.ru».

Раздел LOG.

Хранит настройки лог-сервера комплекса. Среди неописываемых настроек - пути к папкам для сбора журналов.

LOG_storedays. Длительность хранения лог-журналов в днях. По умолчанию «7». По истечении указанного периода журналы удаляются системой. В некоторых случаях объем журналов может достигать нескольких гигабайтов за день.

LOG_root. Абсолютный или относительный путь к папке с лог-журналами. По умолчанию «Log», то есть относительный путь в каталоге клиентского приложения.


Форматы звуковых файлов

Система Oktell в соответствии с настройками осуществляет запись в форматах

· G.711 a-law (64 кБит/сек);
· G.711 mu-law (64 кБит/сек);
· MS GSM 6.10 (13 кБит/сек);

Выбор конкретного кодека осуществляется в клиентском интерфейсе в окне выбора устройств (для пользователей VoIP телефонии). Для CTI каналов в качестве кодека для записи установлен G.711 a-low как наиболее оптимальный. Конкретная коммутация происходит использованием одного из кодеков коммутируемых каналов с наименьшим трафиком. Подробнее в разделе «Телефон». Настраиваемый микшер производит сжатие записанных разговоров в MS GSM 6.10 для хранения. Подробнее в разделе «Упаковка записанных разговоров».

Воспроизведение может осуществляться в форматах

· G.711 a-law (64 кБит/сек);
· G.711 mu-law (64 кБит/сек);
· MS GSM 6.10 (13 кБит/сек);
· PCM 16bit 8000Hz Mono (128 кБит/сек);


Порядок обновления программы в ручном режиме

 Содержание | Назад

Обновление проходит в несколько этапов. При необходимости обновления комплекса инструкция будет дополнительно предоставлена технической поддержкой. Ниже приведены общие этапы.

1. Производится остановка работающего сервера.

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

3. Распакованные файлы сборок клиентского и серверного приложения помещаются в соответствующие каталоги на сервере.

4. Производится корректировка конфигурационных файлов приложений. Основные моменты:
a. Имя (адрес) основной базы данных (сервер);
b. Порты, настроенные для VoIP-телефонии (сервер);
c. Аппаратные серверы, загружаемые системой (сервер);
d. Адрес для подключения к серверу логики (клиент);
e. Адрес и порт для подключения к шлюзу VoIP-телефонии (клиент).

5. Клиентские сборки по маске «oktell.Client*.dll» дополнительно помещаются в каталог серверного приложения.

6. Для последующего обновления всех клиентских рабочих мест сборки клиентского приложения дублируются в каталог серверного приложения «LiveUpdate».

7. Файлы обновления БД перед первым запуском находятся в каталоге сервера «DBAutoUpdate».

8. Запуск сервера.

9. Контроль корректности обновления БД (применение и удаление всех файлов в каталоге обновления «DBAutoUpdate»).

10. Контроль запуска всех аппаратных серверов, работоспособность аппаратной части телефонии.

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


Content

Содержание

 Содержание


Системы автоматизации

телефонного обслуживания

Руководство по интеграции

Предварительное описание интерфейсов

клиентского уровня платформы

версия 2.5