Использования native win32 библиотеки
Работа с 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 ); Отправляет видео-фрейм в качестве собственного видео на сервер. Объект уничтожается внутри функции после отправки.