TSPI_lineSetMediaControl-Funktion (tspi.h)

Artikel
08/26/2023

Die TSPI_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. Die neuen angegebenen Mediensteuerelemente ersetzen alle Steuerelemente, die vor dieser Anforderung für diese Zeile, Adresse oder den Aufruf gültig waren.

Syntax

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

Parameter

hdLine

Das Handle zu einer Zeile.

dwAddressID

Eine Adresse auf dem angegebenen Open Line-Gerät. Ein Adressbezeichner ist einer Adresse dauerhaft zugeordnet. Der Bezeichner bleibt über Betriebssystemupgrades hinweg konstant. TAPI überprüft diesen Parameter nicht, wenn diese Funktion aufgerufen wird.

hdCall

Das Handle für einen Anruf. Der Anrufstatus von hdCall kann ein beliebiger Zustand sein.

dwSelect

Gibt an, ob das Mediensteuerelement einem einzelnen Aufruf zugeordnet ist, der Standard für alle Anrufe an einer Adresse oder der Standard für alle Anrufe in einer Zeile ist. Dieser Parameter verwendet die folgenden LINECALLSELECT_ Konstanten.

lpDigitList

Ein Zeiger auf das Array, das die Ziffern enthält, die Mediensteuerungsaktionen vom Typ LINEMEDIACONTROLDIGIT auslösen sollen. Jedes Mal, wenn eine in der Ziffernliste aufgeführte Ziffer 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

Die Anzahl der Einträge in der lpDigitList. TAPI überprüft diesen Parameter nicht, wenn diese Funktion aufgerufen wird.

lpMediaList

Ein 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

Die Anzahl der Einträge in lpMediaList. TAPI überprüft diesen Parameter nicht, wenn diese Funktion aufgerufen wird.

lpToneList

Ein 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

Die Anzahl der Einträge in lpToneList. TAPI überprüft diesen Parameter nicht, wenn diese Funktion aufgerufen wird.

lpCallStateList

Ein 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.

dwCallStateNumEntries

Die Anzahl der Einträge in lpCallStateList. TAPI überprüft diesen Parameter nicht, wenn diese Funktion aufgerufen wird.

Rückgabewert

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

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.

Hinweise

Diese Funktion gibt null (erfolg) zurück, wenn die Mediensteuerung ordnungsgemäß initiiert wird, nicht, wenn ein Mediensteuerelement wirksam wird. Die derzeit laufende Mediensteuerung wird geändert oder abgebrochen, wenn diese Funktion entweder mit unterschiedlichen Parametern oder NULLs erneut aufgerufen wird.

Nur eine einzelne Mediensteuerungsanforderung kann bei einem Anruf gleichzeitig ausstehen. Eine Anforderung ersetzt alle ausstehenden Elemente.

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

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

Jedes Mal, wenn TSPI_lineSetMediaControl aufgerufen wird, überschreibt die neue Anforderung jedes aktuell aktive Mediensteuerelement. 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 verbleibenden Einstellungen in Kraft bleiben, sollte die Anwendung TSPI_lineSetMediaControl aufrufen, um die vorherigen Parameter für die Teile bereitzustellen, die in Kraft bleiben müssen, und neue Parameter für die Teile, die geändert werden sollen.