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

Статья
08/26/2023

Функция TSPI_lineSetMediaControl включает и отключает действия управления в потоке мультимедиа, связанном с указанной строкой, адресом или вызовом. Действия управления мультимедиа могут активироваться при обнаружении указанных цифр, типов носителей, пользовательских тонов и состояний вызова. Новые указанные элементы управления мультимедиа заменяют все те, которые действовали для данной строки, адреса или вызова до этого запроса.

Синтаксис

LONG TSPIAPI TSPI_lineSetMediaControl(
  HDRVLINE                          hdLine,
  DWORD                             dwAddressID,
  HDRVCALL                          hdCall,
  DWORD                             dwSelect,
  LPLINEMEDIACONTROLDIGIT const     lpDigitList,
  DWORD                             dwDigitNumEntries,
  LPLINEMEDIACONTROLMEDIA const     lpMediaList,
  DWORD                             dwMediaNumEntries,
  LPLINEMEDIACONTROLTONE const      lpToneList,
  DWORD                             dwToneNumEntries,
  LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,
  DWORD                             dwCallStateNumEntries
);

Параметры

hdLine

Дескриптор линии.

dwAddressID

Адрес на данном устройстве с открытой линией. Идентификатор адреса постоянно связан с адресом; идентификатор остается неизменным при обновлении операционной системы. TAPI не проверяет этот параметр при вызове этой функции.

hdCall

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

dwSelect

Указывает, связан ли элемент управления мультимедиа с одним вызовом, является ли он по умолчанию для всех вызовов по адресу или по умолчанию для всех вызовов в строке. Этот параметр использует следующие константы LINECALLSELECT_.

lpDigitList

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

Допустимые цифры для импульсного режима : от 0 до 9. Допустимые цифры для режима DTMF: от "0" до "9", "A", "B", "C", "D", "*", "#".

dwDigitNumEntries

Количество записей в lpDigitList. TAPI не проверяет этот параметр при вызове этой функции.

lpMediaList

Указатель на массив с записями типа LINEMEDIACONTROLMEDIA. Массив содержит записи dwMediaNumEntries . Каждая запись содержит отслеживаемый тип мультимедиа, сведения о типе носителя (например, длительность) и поле элемента управления мультимедиа. При обнаружении типа мультимедиа в списке соответствующее действие управления мультимедиа выполняется в потоке мультимедиа вызова.

dwMediaNumEntries

Количество записей в lpMediaList. TAPI не проверяет этот параметр при вызове этой функции.

lpToneList

Указатель на массив с записями типа LINEMEDIACONTROLTONE. Массив содержит записи dwToneNumEntries . Каждая запись содержит описание отслеживаемого тона, длительность тона и поле элемента управления мультимедиа. При обнаружении сигнала в списке соответствующее действие управления мультимедиа выполняется в потоке мультимедиа вызова.

dwToneNumEntries

Количество записей в lpToneList. TAPI не проверяет этот параметр при вызове этой функции.

lpCallStateList

Указатель на массив с записями типа LINEMEDIACONTROLCALLSTATE. Массив содержит записи dwCallStateNumEntries . Каждая запись содержит состояние вызова и действие управления мультимедиа.

dwCallStateNumEntries

Количество записей в lpCallStateList. TAPI не проверяет этот параметр при вызове этой функции.

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

Возвращает ноль, если функция выполнена успешно, или номер ошибки при возникновении ошибки. Возможные возвращаемые значения:

LINEERR_INVALADDRESSID, LINEERR_INVALPOINTER, LINEERR_INVALCALLHANDLE, LINEERR_INVALTONELIST, LINEERR_INVALCALLSELECT, LINEERR_NOMEM, LINEERR_INVALCALLSTATELIST, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITLIST, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALMEDIALIST.

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

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

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

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

При каждом вызове TSPI_lineSetMediaControl новый запрос переопределяет любой элемент управления мультимедиа, действующий в настоящее время. Если один или несколько параметров lpDigitList, lpMediaList, lpToneList и lpCallStateList имеют значение NULL, соответствующая цифра, тип носителя, тон или элемент управления мультимедиа, активировав состояние вызова, будет отключен. Чтобы изменить только часть параметров элемента управления мультимедиа, оставив остальные параметры в действии, приложение должно вызвать TSPI_lineSetMediaControl предоставления предыдущих параметров для тех частей, которые должны оставаться в силе, и новых параметров для тех частей, которые необходимо изменить.