Просмотр исходного текста страницы Использования native win32 библиотеки

[[Аудио_и_видео_звонки_из_информационных_терминалов_и_банкоматов|Наверх]]

__TOC__

Работа с native Win32 библиотекой SipClientLib.dll предоставляет полную функциональность интеграционной схемы, за исключением работы с камерами для отправки видео-изображения на сервер в ходе установленной сессии. Библиотека принимает на вход изображения, которые необходимо получать в стороннем ПО и передавать ей для отправки на сервер в заданные интервалы времени.


==Перечисления==

Возможные состояния телефона (транка):

 <span style="color:blue">enum</span> SIP_STATE
 {
 SIP_STATE_IDLE = 0,           <span style="color:darkviolet">// телефон </span>
 SIP_STATE_CONNECTING = 1,     <span style="color:darkviolet">// соединение по tcp </span>
 SIP_STATE_CONNECTED = 2,      <span style="color:darkviolet">// соединение по tcp установленно </span>
 SIP_STATE_CALLING = 3,        <span style="color:darkviolet">// телефон начал вызов по сип </span>
 SIP_STATE_INCALL = 4,         <span style="color:darkviolet">// телефон в разговоре </span>
 SIP_STATE_DISCONNECTING = 5,  <span style="color:darkviolet">// разрыв соединения </span>
 };


Поддерживаемые аудио кодеки:

 <span style="color:blue">enum</span> SIP_CODEC
 {
 SIP_CODEC_G711A = 0,
 SIP_CODEC_G711U = 1,
 SIP_CODEC_GSM = 2,
 SIP_CODEC_G729 = 3,
 };


==События (callback-методы)==

'''С++:'''

:<span style="color:blue">typedef DWORD</span> (<span style="color:blue">__stdcall</span> *PFN_SIPCLIENT_EVENTS)(SIP_CALLBACK event, <span style="color:blue">DWORD</span> dwParam, <span style="color:blue">LPCWSTR</span> wzParam);


Возможные типы событий

 <span style="color:blue">enum</span> SIP_CALLBACK
 {
 SIP_CALL_CONNECTED = 0,    <span style="color:darkviolet">// вызов принят : dwparam - 0, szparam - текстовое описание </span>
 SIP_CALL_REJECTED = 1,     <span style="color:darkviolet">// вызов отвергнут : dwparam - код ошибки (SIP), szparam - текстовое описание</span> 
 SIP_CALL_FINISHED = 2,     <span style="color:darkviolet">// вызов завершен : dwparam - инициатор разрыва (1 - localEnd, 0 - remoteEnd),zparam - текстовое описание </span>
   
 SIP_DATA_SENT = 3,         <span style="color:darkviolet">// файл отправлен : dwparam - handle потока </span>
 SIP_DATA_ERROR = 4,        <span style="color:darkviolet">// ошибка отправки файла: dwparam - handle потока, szparam - текстовое описание </span>
 SIP_DATA_INCOME = 5,       <span style="color:darkviolet">// принят запрос на прием файла, параметры: dwParam - handle для потока, wzparam - описание потока. </span>
 SIP_DATA_RECEIVED = 6,     <span style="color:darkviolet">// данные приняты : dwparam - handle потока </span>
   
 SIP_ERROR = 7,             <span style="color:darkviolet">// ошибка соединения : dwparam - код ошибки (SIP), szparam - текстовое описание </span>
 SIP_STATE_CHANGED = 8,     <span style="color:darkviolet">// изменено состояние телефона : dwParam - новое состояние </span>
 SIP_VIDEO_FRAME_READY = 9, <span style="color:darkviolet">// получен следующий видео-кадр : dwparam - HBITMAP нового кадра </span>
 SIP_VIDEO_STARTED = 10,    <span style="color:darkviolet">// видео связь установленна </span>
 SIP_VIDEO_PAUSED = 11,     <span style="color:darkviolet">// входящий видео поток в паузе/остановлен </span>
 };


==Методы==

<u>Инициализация и уничтожение</u>

*'''SIP_API <span style="color:blue">BOOL __stdcall</span> InitSipClientLib ( PFN_SIPCLIENT_EVENTS );''' Инициализация библиотеки.

*'''SIP_API <span style="color:blue">void __stdcall</span> FreeSipClientLib ( );''' Очистка, освобождение ресурсов и завершение работы библиотеки.


<u>Осуществление вызовов</u>

*'''SIP_API <span style="color:blue">BOOL __stdcall</span> Call ( <span style="color:blue">LPCWSTR</span> szMessage );''' Запрос исходящего вызова на соединение с сервером и создания голосовой сессии (соединение по TCP каналу с сервером, передача szUserInfo, при получении положительного ответа совершается звонок на сервер и голосовое соединение с главным сценарием).

*'''SIP_API <span style="color:blue">void __stdcall</span> Hungup ( );''' Завершает активное соединение.

*'''SIP_API <span style="color:blue">BOOL __stdcall</span> SentDTMF ( <span style="color:blue">CHAR</span> chDTMF );''' Отправляет DTMF сигнал на сервер в ходе активной голосовой сессии.


<u>Передача файлов</u>

*'''SIP_API <span style="color:blue">HANDLE __stdcall</span> StartSending ( <span style="color:blue">LPCWSTR</span> szTag, <span style="color:blue">BYTE</span>* pData, <span style="color:blue">int</span> size, <span style="color:blue">BOOL</span> bEOF, <span style="color:blue">int</span>* pSent );''' Инициирует отправку файла на сервер в ходе активной сессии связи. Если файл достаточно больших размеров, то запрашивает для первого блока файла с последующим вызовом метода '''SendBlock''' для отправки других частей файла или '''AbortSending''' для прекращения отправки.

Параметры:
:<span style="color:green">szTag</span> - строка с XML-содержимым, описывающим передаваемый файл. (<fileinfo><key=filesize,
:<span style="color:green">pData</span> - ссылка на буфер с содержимым первой части файла.
:<span style="color:green">size</span> - размер буфера с содержимым в байтах.
:<span style="color:green">bEOF</span> - признак последней отправки (если считана и передается последняя часть файла).
:<span style="color:green">pSent</span> - возвращает количество отправленных байтов.
:Возвращаемое значение - адрес сессии передачи файла для последующего обращения к сессии методами '''SendBlock''' или '''AbortSending'''.


*'''SIP_API <span style="color:blue">int  __stdcall</span> SendBlock ( <span style="color:blue">HANDLE</span> handle, <span style="color:blue">BYTE</span>* pData, <span style="color:blue">int</span> size, <span style="color:blue">BOOL</span> bEOF );''' Инициирует отправку второй и последующих частей файла в ходе одной сессии.

Параметры:
:<span style="color:green">handle</span> - адрес сессии, определенный при вызове метода StartSending.
:<span style="color:green">pData</span> - ссылка на буфер с содержимым первой части файла.
:<span style="color:green">size</span> - размер буфера с содержимым в байтах.
:<span style="color:green">bEOF</span> - признак последней отправки (если считана и передается последняя часть файла).
:Возвращает количество реально отправленных байтов.

*'''SIP_API <span style="color:blue">void __stdcall</span> AbortSending ( <span style="color:blue">HANDLE</span> handle );''' Обрывает сессию отправки файла. Параметр указывает на адрес сессии, определенный при вызове метода '''StartSending'''.

*'''SIP_API <span style="color:blue">BOOL __stdcall</span> ReceiveBlock ( <span style="color:blue">HANDLE</span> handle, <span style="color:blue">BYTE</span>* pData, <span style="color:blue">int</span> size, <span style="color:blue">int</span>* pRecv );''' Получает очередной блок файла. В текущей реализации не используется.

*'''SIP_API <span style="color:blue">void __stdcall</span> AbortReceiving ( <span style="color:blue">HANDLE</span> handle );''' Обрывает сессию получения файла. В текущей реализации не используется.


<u>Запись в лог-журнал</u>

*'''SIP_API <span style="color:blue">void __stdcall</span> LogWrite ( <span style="color:blue">LPCWSTR</span> szTag, <span style="color:blue">LPCWSTR</span> szString);''' Осуществляет запись в лог-журнал, ведущийся библиотекой.


<u>Установка параметров SIP-клиента</u>

*'''SIP_API <span style="color:blue">BOOL __stdcall</span> SetupSIPAccount ( <span style="color:blue">LPCWSTR</span> szDomain, <span style="color:blue">LPCWSTR</span> szSIPProxy, <span style="color:blue">LPCWSTR</span> szRemoteId, <span style="color:blue">LPCWSTR</span> szUserId, <span style="color:blue">LPCWSTR</span> szUserName, <span style="color:blue">LPCWSTR</span> szUserInfo);''' Устанавливает параметры SIP-клиента для последующего совершения исходящих звонков.

Параметры:
:<span style="color:green">szDomain</span> - имя сервера (например: «myhost.ru», «192.168.0.10», и т.д. )
:<span style="color:green">szSIPProxy</span> - IP-адрес или DNS-имя сервера с опциональным портом (например: «myhost.ru», «212.333.111.213:5070»). Порт по умолчанию 5060.
:<span style="color:green">szRemoteId</span> - идентификатор вызываемой службы (должно совпадать с соответствующим параметром в карте).
:<span style="color:green">szUserId</span> - идентификатор абонента (userid) - составная часть sip-адреса user@domain, определяемого сервером как CallerId. Может содержать латинские буквы, цифры, точки и прочие символы, которые могут быть использованы в именах e-mail до символа «@».
:<span style="color:green">szUserName</span> - необязательное имя клиента.
:<span style="color:green">szUserInfo</span> - информация, которую необходимо передать на сервер (при передаче кодируется в utf-8). Строка с любым (возможно XML) содержимым, которая становится доступна серверу в функции сценариев IVR «XML-INFO абонента» и используется для маршрутизации вызова или начального заполнения диалоговых форм оператора или БД.

Возвращаемое значение указывает на успешность выполнения операции.

Установка и получение параметров по отдельности. Применение происходит до осуществления звонка (клиент должен находится в состоянии IDLE). Каждая функция устанавливает значение полей, соответствующих параметрам функции SetupSIPAccount. 

*<span style="color:green">SIP_API BOOL __stdcall GetSIPDomain ( LPWSTR pBuff, int cch );</span>
*<span style="color:green">SIP_API BOOL __stdcall SetSIPDomain ( LPCWSTR newVal );</span>

*<span style="color:green">SIP_API BOOL __stdcall GetSIPProxy ( LPWSTR pBuff, int cch );</span>
*<span style="color:green">SIP_API BOOL __stdcall SetSIPProxy ( LPCWSTR newVal );</span>

*<span style="color:green">SIP_API BOOL __stdcall GetRemoteId ( LPWSTR pBuff, int cch );</span>
*<span style="color:green">SIP_API BOOL __stdcall SetRemoteId ( LPCWSTR newVal );</span>

*<span style="color:green">SIP_API BOOL __stdcall GetUserId ( LPWSTR pBuff, int cch );</span>
*<span style="color:green">SIP_API BOOL __stdcall SetUserId ( LPCWSTR newVal );</span>

*<span style="color:green">SIP_API BOOL __stdcall GetUserName ( LPWSTR pBuff, int cch );</span>
*<span style="color:green">SIP_API BOOL __stdcall SetUserName ( LPCWSTR newVal );</span>

*<span style="color:green">SIP_API BOOL __stdcall GetUserInfo ( LPWSTR pBuff, int cch );</span>
*<span style="color:green">SIP_API BOOL __stdcall SetUserInfo ( LPCWSTR newVal );</span>


<u>Настройка звуковой подсистемы</u>

*'''SIP_API <span style="color:blue">BOOL __stdcall</span> SetupVoiceDevice ( <span style="color:blue">LPCWSTR</span> szSpkDevice, <span style="color:blue">LPCWSTR</span> szMicDevice, <span style="color:blue">SIP_CODEC</span> prefCodec );''' Устанавливает устройства вывода звука (динамик), ввода звука (микрофон) и выбор используемого аудио-кодека.

*'''SIP_API <span style="color:blue">int  __stdcall</span> GetSpkDevCount ( );''' Возвращает количество устройств вывода звука (динамиков) в системе.

*'''SIP_API <span style="color:blue">BOOL __stdcall</span> GetSpkDeviceAt ( <span style="color:blue">int</span> nIndex, <span style="color:blue">LPWSTR</span> pszDeviceName, <span style="color:blue">int</span> cch );''' Возвращает имя устройства вывода звука (динамика) по индексу перечисления в системе.

*'''SIP_API <span style="color:blue">int  __stdcall</span> GetMicDevCount ( );''' Возвращает количество устройств ввода звука (микрофонов) в системе.

*'''SIP_API <span style="color:blue">BOOL __stdcall</span> GetMicDeviceAt ( <span style="color:blue">int</span> nIndex, <span style="color:blue">LPWSTR</span> pszDeviceName, <span style="color:blue">int</span> cch );''' Возвращает имя устройства ввода звука (микрофона) по индексу перечисления в системе.


Установка и получение параметров по отдельности. Применение происходит до осуществления звонка (клиент должен находится в состоянии IDLE). Каждая функция устанавливает значение полей, соответствующих параметрам функции SetupVoiceDevice.

*<span style="color:green">SIP_API BOOL __stdcall GetSelectedSpkDevice ( LPWSTR pBuff, int cch );</span>
*<span style="color:green">SIP_API BOOL __stdcall SetSelectedSpkDevice ( LPCWSTR newVal );</span>
*<span style="color:green">SIP_API BOOL __stdcall GetSelectedMicDevice ( LPWSTR pBuff, int cch );</span>
*<span style="color:green">SIP_API BOOL __stdcall SetSelectedMicDevice ( LPCWSTR newVal );</span>
*<span style="color:green">SIP_API BOOL __stdcall GetPreferredCodec ( SIP_CODEC* pVal );</span>
*<span style="color:green">SIP_API BOOL __stdcall SetPreferredCodec ( SIP_CODEC newVal );</span>


<u>Настройка SOCKS</u>

*'''SIP_API <span style="color:blue">BOOL __stdcall</span> SetupSocksServer ( <span style="color:blue">LPCWSTR</span> szSocksAddress, <span style="color:blue">WORD</span> wPort, <span style="color:blue">LPCWSTR</span> szSocksUser, <span style="color:blue">LPCWSTR</span> szSocksPassword );''' Настройка socks на случай невозможности определить автоматом (не реализовано. клиент может звонить только через NAT или напрямую).


<u>Настройка видео</u>

*'''SIP_API <span style="color:blue">BOOL __stdcall</span> SetupVideoCodec ( <span style="color:blue">BOOL</span> bShowDialog );''' Открывает окно настроек видео-кодека.
*'''SIP_API <span style="color:blue">BOOL __stdcall</span> StartVideo ( <span style="color:blue">int</span> width, <span style="color:blue">int</span> height );''' Начинает прием/передачу видео в ходе текущей активной голосовой сессии с сервером. В качестве параметров принимаются размеры (ширина и высота) кадров.
*'''SIP_API <span style="color:blue">void __stdcall</span> StopVideo ( );''' Прекращает прием/передачу видео.
*'''SIP_API <span style="color:blue">BOOL __stdcall</span> SendNextFrame ( <span style="color:blue">HBITMAP</span> hBitmap );''' Отправляет видео-фрейм в качестве собственного видео на сервер. Объект уничтожается внутри функции после отправки.