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

Материал из Oktell
Перейти к: навигация, поиск

Наверх

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


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

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

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


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

enum SIP_CODEC
{
SIP_CODEC_G711A = 0,
SIP_CODEC_G711U = 1,
SIP_CODEC_GSM = 2,
SIP_CODEC_G729 = 3,
};


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

С++:

typedef DWORD (__stdcall *PFN_SIPCLIENT_EVENTS)(SIP_CALLBACK event, DWORD dwParam, LPCWSTR wzParam);


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

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


Методы

Инициализация и уничтожение

  • SIP_API BOOL __stdcall InitSipClientLib ( PFN_SIPCLIENT_EVENTS ); Инициализация библиотеки.
  • SIP_API void __stdcall FreeSipClientLib ( ); Очистка, освобождение ресурсов и завершение работы библиотеки.


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

  • SIP_API BOOL __stdcall Call ( LPCWSTR szMessage ); Запрос исходящего вызова на соединение с сервером и создания голосовой сессии (соединение по TCP каналу с сервером, передача szUserInfo, при получении положительного ответа совершается звонок на сервер и голосовое соединение с главным сценарием).
  • SIP_API void __stdcall Hungup ( ); Завершает активное соединение.
  • SIP_API BOOL __stdcall SentDTMF ( CHAR chDTMF ); Отправляет DTMF сигнал на сервер в ходе активной голосовой сессии.


Передача файлов

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

Параметры:

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


  • SIP_API int __stdcall SendBlock ( HANDLE handle, BYTE* pData, int size, BOOL bEOF ); Инициирует отправку второй и последующих частей файла в ходе одной сессии.

Параметры:

handle - адрес сессии, определенный при вызове метода StartSending.
pData - ссылка на буфер с содержимым первой части файла.
size - размер буфера с содержимым в байтах.
bEOF - признак последней отправки (если считана и передается последняя часть файла).
Возвращает количество реально отправленных байтов.
  • SIP_API void __stdcall AbortSending ( HANDLE handle ); Обрывает сессию отправки файла. Параметр указывает на адрес сессии, определенный при вызове метода StartSending.
  • SIP_API BOOL __stdcall ReceiveBlock ( HANDLE handle, BYTE* pData, int size, int* pRecv ); Получает очередной блок файла. В текущей реализации не используется.
  • SIP_API void __stdcall AbortReceiving ( HANDLE handle ); Обрывает сессию получения файла. В текущей реализации не используется.


Запись в лог-журнал

  • SIP_API void __stdcall LogWrite ( LPCWSTR szTag, LPCWSTR szString); Осуществляет запись в лог-журнал, ведущийся библиотекой.


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

  • SIP_API BOOL __stdcall SetupSIPAccount ( LPCWSTR szDomain, LPCWSTR szSIPProxy, LPCWSTR szRemoteId, LPCWSTR szUserId, LPCWSTR szUserName, LPCWSTR szUserInfo); Устанавливает параметры SIP-клиента для последующего совершения исходящих звонков.

Параметры:

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

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

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

  • SIP_API BOOL __stdcall GetSIPDomain ( LPWSTR pBuff, int cch );
  • SIP_API BOOL __stdcall SetSIPDomain ( LPCWSTR newVal );
  • SIP_API BOOL __stdcall GetSIPProxy ( LPWSTR pBuff, int cch );
  • SIP_API BOOL __stdcall SetSIPProxy ( LPCWSTR newVal );
  • SIP_API BOOL __stdcall GetRemoteId ( LPWSTR pBuff, int cch );
  • SIP_API BOOL __stdcall SetRemoteId ( LPCWSTR newVal );
  • SIP_API BOOL __stdcall GetUserId ( LPWSTR pBuff, int cch );
  • SIP_API BOOL __stdcall SetUserId ( LPCWSTR newVal );
  • SIP_API BOOL __stdcall GetUserName ( LPWSTR pBuff, int cch );
  • SIP_API BOOL __stdcall SetUserName ( LPCWSTR newVal );
  • SIP_API BOOL __stdcall GetUserInfo ( LPWSTR pBuff, int cch );
  • SIP_API BOOL __stdcall SetUserInfo ( LPCWSTR newVal );


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

  • SIP_API BOOL __stdcall SetupVoiceDevice ( LPCWSTR szSpkDevice, LPCWSTR szMicDevice, SIP_CODEC prefCodec ); Устанавливает устройства вывода звука (динамик), ввода звука (микрофон) и выбор используемого аудио-кодека.
  • SIP_API int __stdcall GetSpkDevCount ( ); Возвращает количество устройств вывода звука (динамиков) в системе.
  • SIP_API BOOL __stdcall GetSpkDeviceAt ( int nIndex, LPWSTR pszDeviceName, int cch ); Возвращает имя устройства вывода звука (динамика) по индексу перечисления в системе.
  • SIP_API int __stdcall GetMicDevCount ( ); Возвращает количество устройств ввода звука (микрофонов) в системе.
  • SIP_API BOOL __stdcall GetMicDeviceAt ( int nIndex, LPWSTR pszDeviceName, int cch ); Возвращает имя устройства ввода звука (микрофона) по индексу перечисления в системе.


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

  • SIP_API BOOL __stdcall GetSelectedSpkDevice ( LPWSTR pBuff, int cch );
  • SIP_API BOOL __stdcall SetSelectedSpkDevice ( LPCWSTR newVal );
  • SIP_API BOOL __stdcall GetSelectedMicDevice ( LPWSTR pBuff, int cch );
  • SIP_API BOOL __stdcall SetSelectedMicDevice ( LPCWSTR newVal );
  • SIP_API BOOL __stdcall GetPreferredCodec ( SIP_CODEC* pVal );
  • SIP_API BOOL __stdcall SetPreferredCodec ( SIP_CODEC newVal );


Настройка SOCKS

  • SIP_API BOOL __stdcall SetupSocksServer ( LPCWSTR szSocksAddress, WORD wPort, LPCWSTR szSocksUser, LPCWSTR szSocksPassword ); Настройка socks на случай невозможности определить автоматом (не реализовано. клиент может звонить только через NAT или напрямую).


Настройка видео

  • SIP_API BOOL __stdcall SetupVideoCodec ( BOOL bShowDialog ); Открывает окно настроек видео-кодека.
  • SIP_API BOOL __stdcall StartVideo ( int width, int height ); Начинает прием/передачу видео в ходе текущей активной голосовой сессии с сервером. В качестве параметров принимаются размеры (ширина и высота) кадров.
  • SIP_API void __stdcall StopVideo ( ); Прекращает прием/передачу видео.
  • SIP_API BOOL __stdcall SendNextFrame ( HBITMAP hBitmap ); Отправляет видео-фрейм в качестве собственного видео на сервер. Объект уничтожается внутри функции после отправки.
Источник — «https://wiki.oktell.ru/index.php?title=Использования_native_win32_библиотеки&oldid=8167»