Сервисное взаимодействие — различия между версиями

Текущая версия на 08:27, 26 марта 2015

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

Событие 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
• dbarbitrarydataset
• dbtransaction
• callnumber
• switchnumber
• callabort
• log
• notify
• tabs
• tabindex
• headertext
• headercolor
• faxsend
• faxabort
• downloadrecordbyid
• downloadrecordsbychain
• uploadfiletoserver
• downloadfilefromserver
• deletefilefromserver
• showdirectoryonserver
• sethandleevent
• svcscriptstart
• headsetcommand
• headsetcheckstate
• getallusersfullinfo
• getspecifieduserfullinfo
• getkeyid
• getqueueitems
• interaction

• db

Осуществляет запрос к БД средствами Oktell.

В теле элемента property_set должно быть указано свойство sqltext. Текст запроса должен иметь полностью сформированный вид и будет передан без дополнительных параметров на сервер, а затем в БД. Запрос должен представлять из себя один batch-блок, и может иметь любую сложность (содержать переменные, курсоры, вести обработку в цикле и т.д.). При необходимости текст запроса может быть преобразован в Base64 (предварительное преобразование в Unicode) и передан через поле sqltextb64. Присутствие одного из них обязательно.

Возвращаемое значение (одиночный набор) будет преобразовано в 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 );

В поле sqltext передается текст запроса SQL. Текст запроса должен иметь полностью сформированный вид и будет передан без дополнительных параметров на сервер, а затем в БД. Запрос должен представлять из себя один batch-блок, и может иметь любую сложность (содержать переменные, курсоры, вести обработку в цикле и т.д.). При необходимости текст запроса может быть преобразован в Base64 (предварительное преобразование в Unicode) и передан через поле sqltextb64. Присутствие одного из них обязательно.

Структура запроса:

<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>

• dbarbitrarydataset

Осуществляет запрос к БД средствами Oktell. В отличие от методов «db» и «dbdataset» позволяет подключаться к различным БД посредством ADO, OLE, ODBC, Oracle. Cтруктуру, получаемую на сервере, загружает в DataSet и формирует на ее базе XML строку, преобразованную в Base64.

Для обратного преобразования необходимо полученную из поля CDATA строку подвергнуть обработке следующим кодом (C#):

DataSet ds = new DataSet();
MemoryStream ms = new MemoryStream ( Convert.FromBase64String ( dsxml ) );
ds.ReadXml ( ms );

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

SQLServerSelf      = 1 //Подключение к БД Oktell
SQLServerOther     = 2 //Подключение к сторонней базе MS SQL
OLE                = 3 //Подключение к OLE-драйверу
Oracle             = 4 //Подключение к Oracle-драйверу
Odbc               = 5 //Подключение к ODBC драйверу

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

Для подключения к сторонним БД необходимо указание строки подключения к БД (поле connectionstring). Если осуществляется подключение к собственной БД Oktell, строка подключения игнорируется.

В поле sqltext передается текст запроса SQL. Текст запроса должен иметь полностью сформированный вид и будет передан без дополнительных параметров на сервер, а затем в БД. Запрос должен представлять из себя один batch-блок, и может иметь любую сложность (содержать переменные, курсоры, вести обработку в цикле и т.д.). При необходимости текст запроса может быть преобразован в Base64 (предварительное преобразование в Unicode) и передан через поле sqltextb64. Присутствие одного из них обязательно.

Структура запроса:

<property_set name="dbarbitrarydataset" id="...">
<property_cdata key="direction" value="3"/>
<property_cdata key="connectionstring"><![CDATA[Provider=Microsoft.Jet.OLEDB.4.0; Data Source=C:\Base; Extended Properties=dBase IV]]>
</property_cdata>
<property_cdata key="sqltext"><![CDATA[...]]></property_cdata>
<property_cdata key="sqltextb64"><![CDATA[...]]></property_cdata>
</property_set>

Если при выполнении запроса возникает ошибка или исключение, то конкретный код исключения возвращается в поле sqlresultcode, а коллекция dataset отсутствует. В случае успешного выполнения код возврата равен 0.

Структура ответа в случае успешного выполнения:

<property_set name="dbarbitrarydataset" id="...">
<property_simple key="resultcode" value="100" name="Success" />
<property_cdata key="resultdescription"><![CDATA[Success]]></property_cdata>
<property_simple key="sqlresultcode" value="0" />
<property_collection name="dataset" count="1">
<property_set name="datasetxmlb64">
 <property_cdata key="xmlb64"><![CDATA[.....Base64......]]></property_cdata>
</property_set>
</property_collection>
</property_set>

• dbtransaction

Осуществляет запрос к БД средствами Oktell. Работает в транзакции. Работа с помощью метода состоит из нескольких этапов: создание подключения и транзакции, поочередное выполнение одного или нескольких запросов с возвратом результата выполнения в виде DataSet, и применении или откате транзакции. Поле mode параметра определяет режим работы (этап):

Сreate        = 1 //Подключение к БД, создание транзакции
Query         = 2 //Выполнение запроса в существующей транзакции
Commit        = 3 //Подтверждение и применение изменений
Rollback      = 4 //Откат транзакции к прежнему состоянию

Режим Create осуществляет подключение к БД и создает транзакцию. Подключение и транзакция сохраняются на сервере до момента выполнения метода OnQuery.dbtransaction в режиме Commit или Rollback. Транзакция автоматически откатывается и подключение закрывается в случае выхода пользователя из системы, но этого режима лучше избегать, так как активная транзакция может парализовать работу других служб. Передаваемый параметр должен содержать указание направления (поле direction) числовым значением из следующего набора:

SQLServerSelf    = 1 //Подключение к БД Oktell
SQLServerOther   = 2 //Подключение к сторонней базе MS SQL
OLE              = 3 //Подключение к OLE-драйверу
Oracle           = 4 //Подключение к Oracle-драйверу
Odbc             = 5 //Подключение к ODBC драйверу

Если требуется подключение к собственной БД Oktell, поле direction можно не указывать. Для подключения к сторонним БД необходимо указание строки подключения к БД (поле connectionstring). Если осуществляется подключение к собственной БД Oktell, строка подключения игнорируется. Необходимо также определить поле checkcode, являющееся произвольным числовым значением, которое будет гарантировать доступ к транзакции только исполнителю. На каждом последующем режиме работы с транзакцией требуется указание того checkcode, который был определен при создании подключения. В противном случае метод не будет выполнен и будет возвращен код соответствующей ошибки (50045). Для создания новой транзакции необходимо сначала дождаться окончания выполнения предыдущей, или закрыть ее принудительно (методами Commit или Rollback с совпадающим кодом checkcode). Если в момент создания уже существует активная транзакция, будет возвращен код ошибки 50047.

Режим Query осуществляет запрос через ранее созданное подключение и активную транзакцию. Cтруктуру, получаемую на сервере, загружает в DataSet и формирует на ее базе XML строку, преобразованную в Base64. Для обратного преобразования необходимо полученную из поля CDATA строку подвергнуть обработке следующим кодом (C#):

DataSet ds = new DataSet();
MemoryStream ms = new MemoryStream ( Convert.FromBase64String ( dsxml ) );
ds.ReadXml ( ms );

В поле sqltext передается текст запроса SQL. Текст запроса должен иметь полностью сформированный вид и будет передан без дополнительных параметров на сервер, а затем в БД. Запрос должен представлять из себя один batch-блок, и может иметь любую сложность (содержать переменные, курсоры, вести обработку в цикле и т.д.). При необходимости текст запроса может быть преобразован в Base64 (предварительное преобразование в Unicode) и передан через поле sqltextb64. Присутствие одного из них обязательно. Также для выполнения запроса в транзакции требуется обязательное указание поля checkcode, которое должно соответствовать значению, определенному при создании подключения и транзакции. В противном случае будет возвращаться код соответствующей ошибки (50045 в случае, если код не совпадает, 50046 в случае, если транзакция не существует).

Режим Commit завершает транзакцию с применением изменений, а также закрывает подключение. После выполнения метода следующее обращение должно вновь создать подключение (возможно к другой БД). Для корректного выполнения метода требуется обязательное указание поля checkcode, значение которого должно соответствовать значению, определенному при создании подключения и транзакции. В противном случае метод не будет выполнен и будет возвращен код соответствующей ошибки.

Режим Rollback завершает транзакцию с откатом изменений, а также закрывает подключение. После выполнения метода следующее обращение должно вновь создать подключение (возможно к другой БД). Для корректного выполнения метода требуется обязательное указание поля checkcode, значение которого должно соответствовать значению, определенному при создании подключения и транзакции. В противном случае метод не будет выполнен и будет возвращен код соответствующей ошибки.

Возможные коды ошибок:

• 50043 - Ошибка выполнения запроса
• 50044 - Ошибка при подключении к указанной БД
• 50045 - Переданный код транзакции не соответствует реальному
• 50046 - Не обнаружена активная транзакция
• 50047 - Транзакция уже существует
• Прочие коды совпадают с кодами ошибок соответствующих драйверов подключения.

Примеры запросов

Создание транзакции:

<property_set name="dbtransaction" id="...">
<property_cdata key="mode" value="1"/>
<property_cdata key="direction" value="3"/>
<property_cdata key="connectionstring"><![CDATA[Provider=Microsoft.Jet.OLEDB.4.0; Data Source=C:\Base; Extended Properties=dBase IV]]>
</property_cdata>
<property_cdata key="checkcode" value="42556232"/>
</property_set>

Выполнение запроса:

<property_set name="dbtransaction" id="...">
<property_cdata key="mode" value="2"/>
<property_cdata key="checkcode" value="42556232"/>
<property_cdata key="sqltext"><![CDATA[...]]></property_cdata>
<property_cdata key="sqltextb64"><![CDATA[...]]></property_cdata>
</property_set>

Применение (откат) транзакции:

<property_set name="dbtransaction" id="...">
<property_cdata key="mode" value="3"/>
<property_cdata key="checkcode" value="42556232"/>
</property_set>

Если при выполнении запроса возникает ошибка или исключение, то конкретный код исключения возвращается в поле sqlresultcode, а коллекция dataset отсутствует. В случае успешного выполнения код возврата равен 0.

Структура ответа в случае успешного выполнения:

<property_set name="dbtransaction" id="...">
<!--##### Общие свойства #####-->
<property_simple key="resultcode" value="100" name="Success" />
<property_cdata key="resultdescription"><![CDATA[Success]]></property_cdata>
<property_simple key="sqlresultcode" value="0" />
<!--##### Возвращаемый набор #####-->
<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

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

<y>Структура запроса:</u>

<property_set name="callabort" id="..." />

Ответ содержит только стандартные поля resultcode и resultdescription.

• log

Осуществляет вывод текстовой информации в стандартный лог-журнал Plugin клиентского приложения Oktell. Текст логируемой строки может быть указан явно (поле logstring) или в виде base64, преобразованного из unicode-кодировки (поле logstringb64).

Указанием поля type можно достичь вывода текстовой строки в лог-журнал Exception (значение "1") или Common (значение "2") клиентского приложения.

Структура запроса:

<property_set name="log" id="...">
<property_simple key="type" value="..." /> ("0" - plugin, "1" - exception, "2" - common)
<property_cdata key="logstring"><![CDATA[...]]></property_cdata>
<property_cdata key="logstringb64"><![CDATA[.....base64.....]]></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="headercolor" 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="downloadrecordsbychain" 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="downloadrecordsbychain" 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 устанавливает при необходимости начальный стартовый параметр, передаваемый в компонент «Старт» сценария. Свойства startparam2 и startparam3 при необходимости устанавливают дополнительные стартовые параметры, доступные в служебном сценарии в разделе функций аргумента (функции «Входной параметр 2» и «Входной параметр 3»). Свойство startmode определяет режим запуска служебного сценария: «1» - асинхронный (только запуск), «2» - синхронный с ожиданием завершения исполнения и возвратом значения из служебной переменной «Возвращаемое значение». По умолчанию при отсутствии параметра выставляется синхронный режим. В синхронном режиме может быть задано свойство timeout, определяющее в секундах максимальное время ожидания завершения работы сценария, по истечению которого сценарий продолжит выполнение, но управление вернется в плагин без ожидания возвращаемого значения.

Структура запроса:

<property_set name="svcscriptstart" id="...">
<property_cdata key="scriptname"><![CDATA[...]]></property_cdata>
<property_simple key="startparam" value="" />
<property_simple key="startparam2" value="" />
<property_simple key="startparam3" 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. В коллекции ответа содержится список всех пользователей с перечнем свойств. В разделе XML-структуры, соответствующей записи пользователя, содержатся такие значения как id, имя, признак оператора, принадлежность к отделу, состояние, присутствие в call-центре, перерыв, переадресация, информация о текущей привязанной линии: идентификатор, номер, код, тип, состояние. Запрашиваемая информация возвращается с сервера состояний и не использует обращения к БД.

Структура ответа:

<property_set name="getallusersfullinfo" id="...">
<property_simple key="resultcode" value="100" name="Success" />
<property_cdata key="resultdescription"><![CDATA[Success]]></property_cdata>
<property_collection name="usersstates" 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="linecode" value="usb16" />
<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>

• getspecifieduserfullinfo

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

Структура запроса:

<property_set name="getspecifieduserfullinfo" id="...">
<property_set name="user">
<property_cdata key="id"><![CDATA[xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx]]></property_cdata>
<property_simple key="login" value="..." />
<property_simple key="name" value="..." />
</property_set>
</property_set>

Ответ содержит стандартные поля resultcode и resultdescription. В коллекции ответа содержится набор данных по одному (запрошенному) пользователю с перечнем свойств. В разделе XML-структуры, соответствующей записи пользователя, содержатся такие значения как id, имя, признак оператора, принадлежность к отделу, состояние, присутствие в call-центре, перерыв, переадресация, информация о текущей привязанной линии: идентификатор, номер, код, тип, состояние. Запрашиваемая информация возвращается с сервера состояний и не использует обращения к БД.

Структура ответа:

<property_set name="getspecifieduserfullinfo" id="...">
<property_simple key="resultcode" value="100" name="Success" />
<property_cdata key="resultdescription"><![CDATA[Success]]></property_cdata>
<property_collection name="usersstates" count="1">
<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="linecode" value="usb16" />
<property_simple key="linetype" value="4" name="ltIntUSB" />
<property_simple key="linestate" value="4" name="lsReady" />
</property_set>
</property_collection>
</property_set>
 

• getkeyid

Осуществляет запрос к серверу для определения текущего регистрационного номера. Возвращает 7-значный номер или 0, если лицензия не обнаружена или неверна.

Структура запроса:

<property_set name="getkeyid" id="...">
</property_set>

Ответ содержит стандартные поля resultcode и resultdescription. Также в структуре ответа содержится поле keyid, содержащее 7-значный регистрационный номер.

Структура ответа:

<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="8378376" />
</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>

• interaction

Осуществляет отправку команды в другой экземпляр plugin-программы, расположенной на другом рабочем месте. Реализует механизм взаимодействия различных экземпляров plugin-программ.

Структура взаимодействия представляет собой цепочку:

Client1.Plugin -> Server -> Client2.Plugin -> Server -> Client1.Plugin

Plugin-программа на первом клиентском рабочем месте инициирует событие OnQuery.interaction, передавая в параметре информацию о пользователе (destinationuserid) или рабочем месте (destinationwpid), куда необходимо передать информацию, код plugin-программы, которая должна обработать запрос (destinationpluginid), а также текстовые данные, подлежащие передаче (data). Запрос отправляется на сервер, и в случае обнаружения запрошенного клиентского места осуществляется вызов метода DoQuery.interaction в указанной plugin-программе, работающей на втором клиентском рабочем месте.

При необходимости возврата ответа (любой информации, запакованной в текстовый вид), экземпляр plugin-программы при обработке вызова DoQuery.interaction может инициировать аналогичный вызов OnQuery.interaction для полностью аналогичной схемы доведения информации в ответ. В качестве адресата указывается пользователь-отправитель, а также plugin-отправитель, коды которых присутствуют в параметре при вызове DoQuery.interaction (senderuserid и senderpluginid). Это асинхронный режим взаимодействия. Вне зависимости от того как долго будет выполняться DoQuery, в какой момент времени будет отправлен асинхронный ответ, управление из вызова OnQuery.interaction в плагине-инициаторе будет возвращено незамедлительно после отправки команды серверу.

В синхронном режиме взаимодействия плагин-инициатор не получает возврата управления из вызова OnQuery.interaction вплоть до возврата управления из метода DoQuery.interaction в плагине-адресате. При этом возвращаемое из DoQuery.interaction значение будет размещено в ответе, подготавливаемом для плагина-инициатора. Для активации синхронного режима в параметре запроса OnQuery.interaction должен быть указан флаг waitrespond со значением «1». В этом случае может быть указан таймаут (timeout), по истечении которого ожидание будет прервано и управление возвращено в инициирующий плагин. Таймаут указывается целым числом в миллисекундах.

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

Если указан идентификатор пользователя (destinationuserid), выбирается рабочее место, на котором он авторизован. В противном случае исследуется идентификатор рабочего места (destinationwpid).

Если клиентское рабочее место обнаружено, происходит отправка запроса на него.

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

Следует иметь в виду, что данные необходимо упаковывать (например в Base64), если они обладают произвольной и/или достаточно сложной структурой. В противном случае их невозможно будет вставить в XML документ.

Структура запроса:

<property_set name="interaction" id="...">
<property_simple key="destinationuserid" value="2" />
<property_cdata key="data"><![CDATA[...произвольные текстовые данные...]]></property_cdata>
<property_simple key="waitrespond" value="1" />
<property_simple key="timeout" value="3000" />
</property_set>

Ответ содержит стандартные поля resultcode и resultdescription. В ответе содержится параметр interactionresult, представляющий собой код результата выполнения запроса. Его значения из набора:

Sent                           = 1   //Операция успешно завершена
DestinationNotSpecified        = 101 //Не указаны параметры клиентского места - назначения
DestinationClientNotFound      = 102 //Клиентское место не найдено
DestinationClientNotLoaded     = 103 //Клиенское место не загружено (пользователь не авторизован)
DestinationPluginNotFound      = 104 //Плагин не найден
DestinationPluginLoadError     = 105 //Плагин не загружен
DestinationClientNotHandled    = 107 //Клиентское место не поддерживает механизм взаимодействия
QueryTimeout                   = 108 //Таймаут ожидания ответа
QueryNoAnswer                  = 109 //Запрос отправлен, но ответ не может быть предоставлен

и параметр resultdata, имеющий значение в случае успешного ожидания выполнения в ходе синхронного запроса. В него подставляется полностью результат выполнения метода DoQuery в плагине-адресате.

Структура ответа:

<property_set name="interaction" id="...">
<property_simple key="resultcode" value="100" name="Success" />
<property_cdata key="resultdescription"><![CDATA[Success]]></property_cdata>
<property_simple key="interactionresult" value="1" name="Sent" />
<property_cdata key="resultdata"><![CDATA[...текстовые данные - результат выполнения...]]></property_cdata>
</property_set>

• getpath

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

• getconfigvalue

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

• getversion

Доступно только для серверных плагинов. Возвращает информацию о версии сервера.

• reloadpbxss

Доступно только для серверных плагинов. Инициирует перезапуск сервера состояний.

• updatehttpsession

Доступно только для серверных плагинов. Обновляет/создает http-сессию на веб-сервере Oktell.

• removehttpsession

Доступно только для серверных плагинов. Удаляет http-сессию на веб-сервере Oktell.

• updateplugin

Доступно только для серверных плагинов. Инициирует обновление плагина

• getcurrentlanguage

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

• getlicense

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

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

Метод 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)
• pluginstarted (20402)
• pluginunload (20403)
• interaction (20501)

• 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-программ, стартующих в режиме без визаулизации вместе с запуском клиентского приложения (устанавливается администратором при регистрации plugin-программы в Oktell). Метод не вызывается при тестовых загрузках администратором, а также если загрузка происходит по первому обращению. В случае динамического обновления метод будет вызван сразу после загрузки обновленной plugin-программы, если для нее установлен момент запуска «При запуске клиентского приложения» или «При запуске главного окна».

<property_set name="pluginloaded" id="20401">
<property_simple key="actiontype" value="20401" name="PluginLoaded" />
</property_set>

• pluginstarted

Код 20402. Вызывается после загрузки всех plugin-программ. Не вызывается после фиктивной загрузки в режимах администрирования и наладки в сценариях. Может применяться и рекомендуется к применению для создания всех внутренних объектов, инициализации визуальных форм, запуска различных процессов, требуемых только в реальной деятельности плагина, и лишних в режиме информационного обмена в административных целях. Рекомендуется именно здесь проводить действия, которые понаитию размещаются в конструкторе управляющего объекта.

<property_set name="pluginstarted" id="20402">
<property_simple key="actiontype" value="20402" name="PluginStarted" />
</property_set>

• pluginunload

Код 20403. Вызывается непосредственно перед выгрузкой plugin-программы в потоке, осуществляющем выгрузку. Ожидается, что plugin-программа осуществит завершение всех активных операций. В случае, если программа подгружена в домен основного приложения, она останется в памяти до его полной выгрузки/перезагрузки. В то же время параллельно может быть загружен новый экземпляр этой же plugin-программы. Необходимо обеспечить освобождение монопольных ресурсов, остановку активных потоков, и другие операции, поддерживаемые в активной фазе работы подпрограммы.

<property_set name="pluginunload" id="20403"> <property_simple key="actiontype" value="20403" name="PluginUnload" /> </property_set>

• interaction

Код 20501. Вызывается по инициативе другой plugin-программы или другого экземпляра этой plugin-программы с передачей произвольной текстовой информации. Может вызываться из экземпляров, запущенных на других клиентских рабочих местах.

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

Подробнее о механизме в описании инициирующего метода OnQuery.interaction.

Следует иметь в виду, что серверное событие, инициирующее вызов этого метода, не производит загрузки соответствующей plugin-программы, а лишь подключение к уже загруженной. Таким образом необходимо гарантировать предварительную загрузку плагина. Это можно организовать принудительной установкой свойства «Момент загрузки» при регистрации plugin-программы в Oktell (значения свойства «При запуске клиентского приложения» или «При запуске главного окна»).

<property_set name="interaction" id="20501">
<property_simple key="actiontype" value="20501" name="Interaction" />
<property_simple key="senderuserid" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />
<property_simple key="senderpluginid" value="817d77a7-5d0e-4783-9304-e310c2ac3443" />
<property_cdata key="data"><![CDATA[...текстовые данные - запрос...]]></property_cdata>
</property_set>

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

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