Работа с HAL — различия между версиями

Текущая версия на 14:25, 21 марта 2017

Методы для работы с 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»-включить микрофон) 
answer      = 6,
refer       = 7,
referto     = 8, (доп. параметр - номер для перевода) 

Формат 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, однако если наверху, то приложение должно знать о том что нужно вводить символ уже в чистое окно. Событие выставляет или снимает режим ожидания очистки при вводе очередного символа. Возникает только при работе с гарнитурой.