lineSetMediaControl-Funktion (tapi.h)

Artikel
03/02/2024

Die lineSetMediaControl-Funktion aktiviert und deaktiviert Steuerungsaktionen für den Medienstream, der der angegebenen Zeile, Adresse oder dem angegebenen Aufruf zugeordnet ist. Mediensteuerungsaktionen können durch die Erkennung von angegebenen Ziffern, Medientypen, benutzerdefinierten Tönen und Anrufzuständen ausgelöst werden.

Syntax

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
);

Parameter

hLine

Handle mit einem Offenzeilengerät.

dwAddressID

Adressbezeichner auf dem angegebenen Open Line-Gerät. Ein Adressbezeichner ist einer Adresse dauerhaft zugeordnet. Der Bezeichner bleibt über Betriebssystemupgrades hinweg konstant.

hCall

Behandeln eines Anrufs. Die Anwendung muss besitzer des Aufrufs sein. Der Anrufstatus von hCall kann ein beliebiger Zustand sein.

dwSelect

Gibt an, ob das angeforderte Mediensteuerelement einem einzelnen Anruf zugeordnet ist, der Standard für alle Anrufe an einer Adresse oder der Standard für alle Anrufe in einer Zeile ist. Dieser Parameter 1 und nur eine der LINECALLSELECT_ Konstanten.

lpDigitList

Zeiger auf das Array, das die Ziffern enthält, die Mediensteuerungsaktionen vom Typ LINEMEDIACONTROLDIGIT auslösen sollen. Jedes Mal, wenn eine Ziffer in der Ziffernliste erkannt wird, wird die angegebene Mediensteuerungsaktion für den Medienstream des Aufrufs ausgeführt.

Gültige Ziffern für den Impulsmodus sind "0" bis "9". Gültige Ziffern für den DTMF-Modus sind "0" bis "9", "A", "B", "C", "D", "*", "#".

dwDigitNumEntries

Anzahl der Einträge in der lpDigitList.

lpMediaList

Zeiger auf ein Array mit Einträgen vom Typ LINEMEDIACONTROLMEDIA. Das Array verfügt über dwMediaNumEntries-Einträge . Jeder Eintrag enthält einen zu überwachenden Medientyp, medientypspezifische Informationen (z. B. Dauer) und ein Mediensteuerungsfeld. Wenn ein Medientyp in der Liste erkannt wird, wird die entsprechende Mediensteuerungsaktion für den Medienstream des Aufrufs ausgeführt.

dwMediaNumEntries

Anzahl der Einträge in lpMediaList.

lpToneList

Zeiger auf ein Array mit Einträgen vom Typ LINEMEDIACONTROLTONE. Das Array verfügt über dwToneNumEntries-Einträge . Jeder Eintrag enthält eine Beschreibung eines zu überwachenden Tones, der Dauer des Tones und eines Mediensteuerungsfelds. Wenn ein Ton in der Liste erkannt wird, wird die entsprechende Mediensteuerungsaktion für den Medienstream des Aufrufs ausgeführt.

dwToneNumEntries

Anzahl der Einträge in lpToneList.

lpCallStateList

Zeiger auf ein Array mit Einträgen vom Typ LINEMEDIACONTROLCALLSTATE. Das Array verfügt über dwCallStateNumEntries-Einträge . Jeder Eintrag enthält einen Aufrufzustand und eine Mediensteuerungsaktion. Wenn der angegebene Aufruf in einen der Aufrufzustände in der Liste übertritt, wird die entsprechende Mediensteuerungsaktion aufgerufen.

dwCallStateNumEntries

Anzahl der Einträge in lpCallStateList.

Rückgabewert

Gibt null zurück, wenn die Anforderung erfolgreich ist, oder eine negative Fehlernummer, wenn ein Fehler auftritt. Mögliche Rückgabewerte sind:

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.

Hinweise

Die lineSetMediaControl-Funktion gilt als erfolgreich, wenn die Mediensteuerung ordnungsgemäß initiiert wurde, nicht, wenn ein Mediensteuerelement wirksam wurde. Die derzeit ausgeführte Mediensteuerung wird geändert oder abgebrochen, indem diese Funktion entweder mit unterschiedlichen Parametern oder NULLs erneut aufgerufen wird. Wenn mindestens einer der Parameter lpDigitList, lpMediaList, lpToneList und lpCallStateListNULL ist, ist die entsprechende Ziffer, der Medientyp, der Ton oder das vom Aufrufzustand ausgelöste Mediensteuerelement deaktiviert. Um nur einen Teil der Mediensteuerungsparameter zu ändern, während die restlichen Einstellungen in Kraft bleiben, sollte die Anwendung lineSetMediaControl aufrufen und die vorherigen Parameter für die Teile bereitstellen, die in Kraft bleiben müssen, und neue Parameter für die Teile, die geändert werden sollen.

Wenn hCall ausgewählt ist und der Anruf beendet wird oder die Anwendung den Handle zugeordnet, wird die Mediensteuerung für diesen Anruf abgebrochen.

Alle Anwendungen, die Besitzer des Aufrufs sind, dürfen grundsätzlich Mediensteuerungsanforderungen für den Anruf stellen. Nur eine einzelne Mediensteuerungsanforderung kann für einen Anruf für alle Anwendungen, die den Anruf besitzen, ausstehen. Jedes Mal, wenn lineSetMediaControl aufgerufen wird, überschreibt die neue Anforderung alle Mediensteuerelemente, die dann für den Aufruf wirksam sind, unabhängig davon, ob sie von der aufrufenden Anwendung oder einer anderen besitzenden Anwendung festgelegt wurde.

Je nach Dienstanbieter und anderen Aktivitäten, die um solche Ressourcen konkurrieren, kann die Anzahl der gleichzeitigen Erkennungen, die durchgeführt werden können, im Laufe der Zeit variieren. Wenn Dienstanbieterressourcen überlastet werden, wird der LINEERR_RESOURCEUNAVAIL-Fehler zurückgegeben.

Ob die Mediensteuerung vom Dienstanbieter unterstützt wird, ist eine Gerätefunktion.