Функция lineSetMediaControl (tapi.h)

Статья
03/08/2023

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

Синтаксис

LONG lineSetMediaControl(
  HLINE                             hLine,
  DWORD                             dwAddressID,
  HCALL                             hCall,
  DWORD                             dwSelect,
  LPLINEMEDIACONTROLDIGIT const     lpDigitList,
  DWORD                             dwDigitNumEntries,
  LPLINEMEDIACONTROLMEDIA const     lpMediaList,
  DWORD                             dwMediaNumEntries,
  LPLINEMEDIACONTROLTONE const      lpToneList,
  DWORD                             dwToneNumEntries,
  LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,
  DWORD                             dwCallStateNumEntries
);

Параметры

hLine

Дескриптор к устройству с открытой линией.

dwAddressID

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

hCall

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

dwSelect

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

lpDigitList

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

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

dwDigitNumEntries

Количество записей в lpDigitList.

lpMediaList

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

dwMediaNumEntries

Количество записей в lpMediaList.

lpToneList

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

dwToneNumEntries

Количество записей в lpToneList.

lpCallStateList

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

dwCallStateNumEntries

Количество записей в lpCallStateList.

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

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

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

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

Если выбран параметр hCall и вызов завершается или приложение освобождает свой дескриптор, управление мультимедиа в этом вызове отменяется.

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

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

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