функция TSPI_lineSetupConference (tspi.h)

Статья
08/26/2023

Функция TSPI_lineSetupConference настраивает конференцию для добавления стороннего поставщика.

Синтаксис

LONG TSPIAPI TSPI_lineSetupConference(
  DRV_REQUESTID          dwRequestID,
  HDRVCALL               hdCall,
  HDRVLINE               hdLine,
  HTAPICALL              htConfCall,
  LPHDRVCALL             lphdConfCall,
  HTAPICALL              htConsultCall,
  LPHDRVCALL             lphdConsultCall,
  DWORD                  dwNumParties,
  LPLINECALLPARAMS const lpCallParams
);

Параметры

dwRequestID

Идентификатор асинхронного запроса.

hdCall

Дескриптор начального звонка, который определяет первую сторону конференции. В некоторых средах для начала конференции должен существовать вызов. В других средах телефонии изначально не существует вызова, и hdCall остается null. Состояние вызова hdCall может быть подключено.

hdLine

Дескриптор устройства линии, на котором будет выполняться конференция, если hdCall имеет значение NULL. Параметр hdLine игнорируется, если hdCall имеет значение, отличное от NULL. Поставщик услуг сообщает, какую модель он поддерживает, используя флаг setupConfNull структуры данных LINEADDRESSCAPS .

htConfCall

Дескриптор TAPI для новой конференции. Поставщик услуг должен сохранить его и использовать во всех последующих вызовах процедуры LINEEVENT , сообщая о событиях нового вызова.

lphdConfCall

Указатель на HDRVCALL , представляющий идентификатор поставщика услуг для вновь созданного конференц-звонка. Поставщик услуг должен заполнить это расположение своим дескриптором для нового вызова, прежде чем эта процедура вернет. Этот дескриптор игнорируется TAPI, если функция приводит к ошибке. Состояние вызова hdConfCall неприменимо.

htConsultCall

Дескриптор TAPI к консультационному вызову. При создании вызова для добавления новой стороны автоматически выделяется новый временный звонок (консультационный звонок). Поставщик услуг должен сохранить htConsultCall и использовать его во всех последующих вызовах процедуры LINEEVENT , сообщая о событиях нового консультационного звонка.

lphdConsultCall

Указатель на HDRVCALL , представляющий идентификатор поставщика услуг для вызова. При создании вызова для добавления новой стороны автоматически выделяется новый временный звонок (консультационный звонок). Поставщик услуг должен заполнить это расположение своим дескриптором для нового вызова консультации, прежде чем эта процедура будет возвращена. Этот дескриптор игнорируется TAPI, если функция приводит к ошибке. Состояние вызова hdConsultCall неприменимо.

dwNumParties

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

lpCallParams

Указатель на структуру LINECALLPARAMS , содержащую параметры вызова, используемые при установлении консультационного звонка. Этот параметр имеет значение NULL , если специальные параметры настройки вызова не требуются и поставщик услуг использует параметры по умолчанию.

Возвращаемое значение

Возвращает dwRequestID или номер ошибки при возникновении ошибки. Фактический параметр lResult соответствующего ASYNC_COMPLETION равен нулю, если функция выполнена успешно, или номер ошибки в случае возникновения ошибки. Возможные возвращаемые значения:

LINEERR_INVALCALLHANDLE, LINEERR_INVALADDRESSMODE, LINEERR_INVALLINEHANDLE, LINEERR_INVALBEARERMODE, LINEERR_INVALCALLSTATE, LINEERR_INVALCALLPARAMS, LINEERR_CALLUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_CONFERENCEFULL, LINEERR_INVALMEDIAMODE, LINEERR_NOMEM, LINEERR_INVALRATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INUSE, LINEERR_OPERATIONFAILED, LINEERR_RATEUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_USERUSERINFOTOOBIG LINEERR_BEARERMODEUNAVAIL.

Поставщик услуг возвращает LINEERR_INVALLINEHANDLE, если указанный дескриптор строки для строки, содержащей конференцию, недопустим. Эта ошибка также может указывать на то, что среда телефонии требует начальной строки для настройки конференции, но вместо этого был указан дескриптор вызова, отличный от NULL .

Поставщик услуг возвращает LINEERR_INVALCALLHANDLE, если среда телефонии требует первоначального вызова для настройки конференции, но вместо этого был указан дескриптор вызова NULL .

TSPI_lineSetupConference предоставляет два способа организации нового конференц-звонка в зависимости от того, требуется ли обычный вызов с двумя участниками. При настройке конференции из существующего двухстороннего вызова параметр hdCall является допустимым дескриптором звонка, который изначально добавляется в конференцию TSPI_lineSetupConference запросом, а hdLine игнорируется. На коммутаторах, где настройка конференц-связи не начинается с существующего звонка, hdCall должен иметь значение NULL и hdLine , чтобы определить устройство линии, на котором следует инициировать конференцию. В любом случае для подключения к стороне, которая должна быть добавлена к звонку, выделяется консультационный звонок. TAPI может использовать TSPI_lineDial для набора адреса другой стороны.

Конференц-связь обычно переходит в состояние onHoldPendingConference , состояние dialtone для консультационного вызова и начальный вызов (если таковой) переходит в состояние конференц-связи .

Конференц-звонок также можно настроить с помощью функции TSPI_lineCompleteTransfer , которая разрешается в трехсторонняя конференция.

TAPI может иметь возможность переключаться между конференц-связью и конференц-связью с помощью TSPI_lineSwapHold.

Функция TSPI_lineUnhold может восстанавливать вызовы, которые имеют состояние вызова onHoldPendingConference. В этом случае любой звонок на консультацию обычно переходит в состояние простоя .

Звонок на консультацию можно отменить, вызвав TSPI_lineDrop на нем. При удалении консультационного звонка существующая конференц-связь обычно переходит обратно в подключенное состояние. TAPI и его клиентские приложения должны отслеживать LINE_CALLSTATE сообщения, чтобы точно определить, что происходит с вызовами. Например, если конференц-связь возвращается к обычному двухстороннему вызову, конференц-связь становится бездействующей, а исходный звонок участника может отменить изменения к подключенной.

Эта функция отличается от соответствующей функции TAPI тем, что она следует модели TSPI для начала времени существования вызова. TAPI и поставщик услуг обмениваются непрозрачными дескрипторами, представляющими вызов друг с другом. Кроме того, поставщик услуг может выполнять обратные вызовы для нового вызова, прежде чем он возвратится из этой процедуры. В любом случае поставщик услуг также должен считать возвращенный дескриптор "еще недействителен" до тех пор, пока соответствующее ASYNC_COMPLETION сообщение не сообщит об успешном выполнении . Иными словами, он не должен выдавать сообщения LINEEVENT для нового вызова или включать их в число вызовов в сообщениях или структурах данных о состоянии для строки.