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

Статья
08/26/2023

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

Синтаксис

LONG TSPIAPI TSPI_lineMakeCall(
  DRV_REQUESTID          dwRequestID,
  HDRVLINE               hdLine,
  HTAPICALL              htCall,
  LPHDRVCALL             lphdCall,
  LPCWSTR                lpszDestAddress,
  DWORD                  dwCountryCode,
  LPLINECALLPARAMS const lpCallParams
);

Параметры

dwRequestID

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

hdLine

Дескриптор строки, в которой должен быть создан новый вызов.

htCall

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

lphdCall

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

lpszDestAddress

Указатель на строку Юникода, завершающуюся значением NULL, которая указывает адрес назначения. Это соответствует стандартному формату набираемого номера. Этот указатель можно указать как NULL для ненабранных адресов (как и для горячего телефона, который всегда автоматически подключается к предопределенным номерам) или при выполнении всех наборов с помощью TSPI_lineDial. В последнем случае TSPI_lineMakeCall выделяет доступный внешний вид звонка, который обычно остается в состоянии dialtone до начала набора. Поставщики служб, имеющие возможности обратного мультиплексирования, могут позволить приложению указать несколько адресов одновременно.

dwCountryCode

Код страны или региона вызываемой стороны. Если указано значение 0, реализация использует значение по умолчанию.

lpCallParams

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

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

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

LINEERR_ADDRESSBLOCKED, LINEERR_INVALLINESTATE, LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALRATE, LINEERR_CALLUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_DIALBILLING, LINEERR_INVALADDRESS, LINEERR_DIALQUIET, LINEERR_INVALADDRESSID, LINEERR_DIALDIALTONE, LINEERR_INVALCALLPARAMS, LINEERR_DIALPROMPT, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALBEARERMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_ INVALCOUNTRYCODE, LINEERR_RATEUNAVAIL, LINEERR_INVALMEDIAMODE LINEERR_USERUSERINFOTOOBIG.

Поставщик услуг возвращает LINEERR_INVALLINESTATE, если строка в настоящее время не находится в состоянии, в котором может выполняться эта операция. Список допустимых на данный момент операций можно найти в элементе dwLineFeatures (типа LINEFEATURE) в структуре LINEDEVSTATUS . (Вызов TSPI_lineGetLineDevStatus обновляет сведения в LINEDEVSTATUS.)

Если поставщик услуг возвращает LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE или LINEERR_DIALPROMPT, он не должен выполнять никаких действий, которые в противном случае выполняются TSPI_lineMakeCall. Например, нет частичного набора номера и выключения. Это связано с тем, что поставщик услуг должен предварительно проверить число на наличие неподдерживаемых символов.

После того как TSPI_lineMakeCall вернет приложению сообщение обратного вызова SUCCESS, поставщик услуг должен отправить LINE_CALLSTATE сообщения в lpfnEventProc , переданный в TSPI_lineOpen , чтобы уведомить TAPI о ходе вызова. Типичной сообщаемой последовательностью может быть звонок, набор номера, продолжение, обратный звонок и подключение; Первое сообщаемое состояние не обязательно LINECALLSTATE_DIALTONE. Поставщик услуг выбирает, сколько из этих состояний будет сообщено. Рекомендуется отправлять как можно больше, чтобы приложения могли выполнять соответствующие действия.

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

Если строка набора номера имеет значение NULL, поставщик услуг принимает строку в состояние dialtone (для поставщика услуг на основе Comm это будет включать ATD) и отправляет сообщение о состоянии вызова с указанием LINECALLSTATE_DIALTONE.

Если строка набора заканчивается на ";" (точка с запятой) поставщик услуг набирает частичный номер и отправляет LINECALLSTATE_DIALING сообщение. Этот вызов завершается вызовами TSPI_lineDial.

Если строка набора содержит символы (W, @, $, ?), которые не поддерживаются поставщиком услуг, поставщик услуг должен сканировать строку набора и (синхронно) возвращать ошибку, соответствующую первому недопустимому символу.

Если установлен флаг LINECALLPARAMFLAGS_IDLE, поставщик услуг должен проверка текущее состояние строки (эквивалентное выключению и распознаванию звонка). Если этот флаг IDLE установлен, а тон набора номера отсутствует, функция завершается сбоем с ошибкой LINEERR_CALLUNAVAIL. Если флаг IDLE не установлен или есть тон набора номера, набор можно продолжить.

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