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

Статья
03/13/2024

Функция TSPI_lineSetupTransfer инициирует передачу вызова, указанного в hdCall. Он устанавливает консультационный звонок , lphdConsultCall, по которому можно набрать сторону, которая может стать местом назначения передачи.

Синтаксис

LONG TSPIAPI TSPI_lineSetupTransfer(
  DRV_REQUESTID          dwRequestID,
  HDRVCALL               hdCall,
  HTAPICALL              htConsultCall,
  LPHDRVCALL             lphdConsultCall,
  LPLINECALLPARAMS const lpCallParams
);

Параметры

dwRequestID

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

hdCall

Дескриптор передаваемого вызова. Состояние вызова hdCall может быть подключено.

htConsultCall

ТАПИ дескриптор нового, временного консультационного звонка. Поставщик услуг должен сохранить этот параметр и использовать его во всех последующих вызовах процедуры LINEEVENT , сообщая о событиях при новом консультационном вызове.

lphdConsultCall

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

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

Эта процедура передачи может быть недопустимой для некоторых линейных устройств. Вместо вызова этой процедуры TAPI может потребоваться отменить существующий удержанный вызов (используя TSPI_lineUnhold), чтобы определить место назначения передачи. На коммутаторах, поддерживающих переключение звонков по нескольким адресам, звонок на консультацию может находиться по адресу, отличному от адреса звонка, который требуется перенести. Кроме того, может потребоваться настроить консультационный звонок как совершенно новый вызов, используя TSPI_lineMakeCall, к месту назначения передачи.

Флаги transferHeld и transferMake в структуре данных LINEADDRESSCAPS сообщают, какую модель использует поставщик услуг.

lpCallParams

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

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

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

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

Эта операция настраивает передачу вызова, указанного в hdCall. На этапе настройки передачи устанавливается консультационный звонок для отправки адреса назначения (стороны, в которую необходимо передать) в коммутатор, в то время как звонок, который будет переведен, остается на удержании. Этот новый вызов называется консультационным вызовом (hdConsultCall) и может управляться (например, удален) независимо от исходного вызова.

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

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

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

В средах телефонии, которые следуют моделям передачи transferHeld или transferMake , эта процедура возвращает LINEERR_OPERATIONFAILED и не выделяет дескриптор консультационного вызова.

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

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