Подключение к COM-объекту — различия между версиями

Текущая версия на 11:02, 1 апреля 2014

Работа с COM-объектом считается устаревшей и не поддерживает ряд методов, в частности работу с видео сессиями. Развитие COM-библиотеки приостановлено. Взамен была предложена альтернатива по работе с native win32 библиотекой.

Регистрация COM-библиотеки

COM объект представлен одной библиотекой (SipClient.dll). Его регистрация осуществляется стандартным способом при помощи утилиты regsvr32.exe.

• Команда для исполнения регистрации выглядит:

regsvr32 SipClient.dll

либо

путь\regsvr32 путь\SipClient.dll

• Команда для удаления регистрации:

regsvr32 /u SipClient.dll

После успешной регистрации (о чем будет сообщено дополнительно в диалоговом окне), в списке доступных COM-объектов будет присутствовать и объект SipClientObj.

Регистрация объекта скорее всего должна производиться в момент установки приложения.

Информация о COM-объекте

Полное имя объекта: SipClientObj

GUID объекта: 2E6048CC-CCE1-4DEA-BB30-76BC3CEB92A1

Интерфейс для вызова методов: interface ISipClient

GUID интерфейса: F75E3D25-9095-4152-87DF-DF85ECFBD553

Интерфейс для callback-методов: dispinterface _ISIPClientEvents

GUID интерфейса: CDFD5DB2-2C32-425E-A95E-D330B9EF9D5A

Библиотека: SipClient 1.0 Type Library

GUID библиотеки: 8A4C2812-8D07-49D2-BD1A-1B66400C8E29

Используемые наборы-перечисления

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

typedef enum
{
       SIPCODEC_G711A,
       SIPCODEC_G711U,
       SIPCODEC_GSM,
       SIPCODEC_G729,

} SIPCODEC;

Состояния SIP-клиента:

typedef enum
{
       SIPSTATE_IDLE,            // состояние покоя
       SIPSTATE_CONNECTING,      // производится соединение с сервером (передача информации)
       SIPSTATE_CONNECTED,       // связь с сервером установленна - переход к вызову оператора
       SIPSTATE_CALLING,         // вызов оператора
       SIPSTATE_INCALL,          // в разговоре
       SIPSTATE_DISCONNECTING,   // разрыв соединения

} SIPSTATE;

Интерфейс обращений ISIPClient

Настройка параметров вызова. Применение происходит до осуществления звонка. Настоятельно не рекомендуется изменять значения во время сеанса связи.

HRESULT SetupSIPAccount ( 
[in] BSTR szDomain, 
[in] BSTR szSIPProxy, 
[in] BSTR szRemoteId, 
[in] BSTR szUserId, 
[in] BSTR szUserName, 
[in] BSTR szUserInfo
)

Устанавливает параметры SIP-клиента. Перед осуществлением звонка необходимо установить значения в соответствии с решаемой задачей, и только после этого произвести вызов. Необходимо указать имя или адрес основного сервера, который должен обработать этот вызов

• szDomain имя сервера (например: myhost.ru)
• szSIPProxy ip адрес или днс имя сервера с опциональным портом (например: myhost.ru, 212.333.111.213:5070)

порт по умолчанию 5060

• szRemoteId идентификатор вызываемой службы (должно совпадать с соответствующим параметром в карте)
• szUserId идентификатор клиента (произвольно, но не пустой)
• szUserName не обязательное имя клиента
• szUserInfo информация которую необходимо передать на сервер (при передаче кодируется в utf-8)

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

• HRESULT SIPDomain ( [out, retval] BSTR* pVal )
• HRESULT SIPDomain ( [in] BSTR newVal )

• HRESULT SIPProxy ( [out, retval] BSTR* pVal )
• HRESULT SIPProxy ( [in] BSTR newVal )

• HRESULT RemoteId ( [out, retval] BSTR* pVal )
• HRESULT RemoteId ( [in] BSTR newVal )

• HRESULT UserId ( [out, retval] BSTR* pVal )
• HRESULT UserId ( [in] BSTR newVal )

• HRESULT UserName ( [out, retval] BSTR* pVal )
• HRESULT UserName ( [in] BSTR newVal )

• HRESULT UserInfo ( [out, retval] BSTR* pVal )
• HRESULT UserInfo ( [in] BSTR newVal )

Настройки звуковой подсистемы. Применение происходит до осуществления звонка. Настоятельно не рекомендуется изменять значения во время сеанса связи.

• HRESULT GetSpkDevCount ( [out, retval] int* pCount )

Возвращает количество доступных устройств вывода звука (динамиков).

• HRESULT GetSpkDeviceAt ( [in] int nIndex, [out, retval] BSTR* pszDeviceName )

Возвращает название устройства вывода звука (динамика) по порядковому индексу. Используется в дальнейшем для установки устройства функцией SetupVoiceDevice.

• HRESULT GetMicDevCount ( [out, retval] int* pCount )

Возвращает количество доступных устройств ввода звука (микрофонов).

• HRESULT GetMicDeviceAt ( [in] int nIndex, [out, retval] BSTR* pszDeviceName )

Возвращает название устройства ввода звука (микрофона) по порядковому индексу. Используется в дальнейшем для установки устройства функцией SetupVoiceDevice.

• HRESULT SetupVoiceDevice ( [in] BSTR szSpkDevice, [in] BSTR szMicDevice, [in] SIPCODEC prefCodec )

Устанавливает указанные устройства в качестве микрофона и в качестве динамика, а также приоритетный звуковой кодек из приведенного выше набора.

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

• HRESULT SelectedSpkDevice ( [out, retval] BSTR* pVal )

Возвращает текущее выбранное устройство вывода звука (динамик).

• HRESULT SelectedSpkDevice ( [in] BSTR newVal )

Устанавливает текущее выбранное устройства вывода звука (динамик). Отдельная альтернатива функции SetupVoiceDevice.

• HRESULT SelectedMicDevice ( [out, retval] BSTR* pVal )

Возвращает текущее выбранное устройство ввода звука (микрофон).

• HRESULT SelectedMicDevice ( [in] BSTR newVal )

Устанавливает текущее выбранное устройства вывода звука (динамик). Отдельная альтернатива функции SetupVoiceDevice.

• HRESULT PreferredCodec ( [out, retval] SIPCODEC* pVal )

Возвращает текущий выбранный предпочитаемый кодек.

• HRESULT PreferredCodec ( [in] SIPCODEC newVal )

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

Управление вызовом.

• HRESULT Call ( [out, retval] VARIANT_BOOL* pRes )

Осуществление вызова (соединение по TCP с сервером, передача szUserInfo, после положительного ответа совершается звонок оператору по UDP). Предварительно необходимо установить параметры вызовом SetupSIPAccount.

• HRESULT Hungup ( void )

Завершает текущее активное соединение.

• HRESULT SentDTMF ( [in] CHAR chDTMF, [out, retval] VARIANT_BOOL* pRes )

Генерирует и отправляет DTMF сигнал на сервер. Может пригодиться для взаимодействия с голосовым меню и ввода дополнительной информации.

Не реализованные функции.

• HRESULT SendUserMessage ( [in] BSTR szMessage )

Отправляет текстовое сообщение в ходе разговора.

• HRESULT SetupSocksServer ( [in] BSTR szSocksAddress, [in] WORD wPort, [in] BSTR szSocksUser, [in] BSTR szSocksPassword )

Настройка SOCKS на случай невозможности определить автоматом. В текущей реализации объект может осуществлять вызов только через NAT или через прямое подключение к интернет.

Интерфейс событий _ISIPClientEvents

• void OnCallConnected ( [in] BSTR info )

Соединение прошло успешно. Объект находится в разговоре.

• void OnCallRejected ( [in] BSTR reason )

Вызов отклонен. В строке-параметре передается информация о причине отказа.

• void OnCallFinished ( [in] VARIANT_BOOL localEnd, [in] BSTR eventInfo )

Вызов завершен. Параметр указывает - локальный

• void OnDataSent ( void )

Данные отправлены (только при использовании SendUserMessage - не реализовано).

• void OnDataReceive ( [in] BSTR data )

Данные получены (только при использовании SendUserMessage - не реализовано).

• void OnError ( [in] BSTR errorText )

Произошла ошибка. Строковый параметр содержит описание.

• void OnStateChanged ( [in] SIPSTATE newState )

Изменилось состояние объекта. Параметр передает новое состояние из приведенного выше набора состояний.