TSPI_lineMonitorTones-Funktion (tspi.h)

Artikel
03/06/2024

Die funktion TSPI_lineMonitorTones aktiviert und deaktiviert die Erkennung von Inbandtönen auf dem Aufruf. Jedes Mal, wenn ein angegebener Ton erkannt wird, wird eine Nachricht über TAPI an die Clientanwendung gesendet.

Syntax

LONG TSPIAPI TSPI_lineMonitorTones(
  HDRVCALL                hdCall,
  DWORD                   dwToneListID,
  LPLINEMONITORTONE const lpToneList,
  DWORD                   dwNumEntries
);

Parameter

hdCall

Der Handle für den Aufruf, für den die Tonerkennung durchgeführt werden soll. Der Aufrufstatus von hdCall kann ein beliebiger Zustand mit Ausnahme des Leerlaufs sein.

dwToneListID

Der eindeutige Bezeichner für diese Tonliste. Mehrere Tonlisten können gleichzeitig hervorragend sein. Der Dienstanbieter muss jede alte Liste mit der gleichen dwToneListID durch die neue Tonliste ersetzen. Wenn lpToneListNULL ist, wird die Tonliste mit dwToneListID einfach gelöscht. In jedem Fall bleiben andere Tonlisten mit unterschiedlichen dwToneListIDsunverändert.

lpToneList

Eine Liste der zu überwachenden Töne vom Typ LINEMONITORTONE. Jeder Ton in dieser Liste verfügt über ein anwendungsdefiniertes Tagfeld, das verwendet wird, um einzelne Töne in der Liste zu identifizieren, um eine Tonerkennung zu melden. Die laufende Tonüberwachung wird abgebrochen oder geändert, indem dieser Vorgang entweder mit NULL für lpToneList oder mit einer anderen Tonliste aufgerufen wird. Der Dienstanbieter muss die Tonliste zur späteren Referenz in seinen eigenen Speicher kopieren, anstatt den Zeiger einfach im Anwendungsspeicher beizubehalten.

dwNumEntries

Die Anzahl der Einträge in lpToneList. Der dwNumEntries-Parameter wird ignoriert, wenn lpToneListNULL ist. 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:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALTONE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_INVALPOINTER.

Hinweise

Diese Funktion gibt null (erfolg) zurück, wenn die Tonüberwachung ordnungsgemäß initiiert wurde, nicht, wenn die Tonüberwachung beendet wird. Wie bei der Medienüberwachung bleibt die Tonüberwachung für eine bestimmte Tonliste wirksam, bis diese Tonliste explizit deaktiviert wird, indem TSPI_lineMonitorTones mit derselben dwToneListID und einer anderen Tonliste (oder einer NULL-Tonliste ) aufgerufen wird, oder bis der Aufruf in den Leerlauf wechselt.

Obwohl diese Funktion in jedem Aufrufzustand außer im Leerlauf aufgerufen werden kann, können Töne in der Regel nur erkannt werden, wenn sich der Aufruf im Zustand verbunden befindet. Die Tonerkennung erfordert in der Regel Rechenressourcen. Abhängig vom Dienstanbieter und anderen Aktivitäten, die um solche Ressourcen konkurrieren, kann die Anzahl der Töne, die erkannt werden können, im Laufe der Zeit variieren. Außerdem kann eine äquivalente Menge von Ressourcen für die Überwachung eines einzelnen dreifachen Frequenztons im Vergleich zu drei einzelnen Frequenztönen verbraucht werden. Wenn Ressourcen überlasten, gibt der Dienstanbieter LINEERR_RESOURCEUNAVAIL zurück.

Der Dienstanbieter überwacht alle Töne in allen Tonlisten gleichzeitig. Wenn ein Ton erkannt wird, wird jeder übereinstimmende Ton aus jeder Tonliste separat mithilfe einer LINE_MONITORTONE Meldung gemeldet. Jeder Tonbericht enthält sowohl den Tonlistenbezeichner als auch das anwendungsspezifische Tag. Einige Dienstanbieter sind möglicherweise nicht in der Lage, sehr enge Töne zu unterscheiden, sodass mehrere Übereinstimmungen auch für Töne gemeldet werden können, deren Beschreibungen nicht streng identisch sind.

Beachten SieTSPI_lineMonitorTones auch verwendet wird, um Stille zu erkennen. Stille wird als Ton mit allen Nullfrequenzen angegeben.

Die entsprechende Funktion auf TAPI-Ebene enthält keinen dwToneListID-Parameter . Die Einbindung dieses Parameters in die TSPI-Schnittstelle ermöglicht es TAPI, die Vereinigung aller Tonüberwachungslisten von allen Anwendungen an den Dienstanbieter weiterzuleiten und gleichzeitig die Möglichkeit zu behalten, die Tonerkennungsereignisse entsprechend der Anwendung zu filtern und weiterzuleiten. Dies gibt Dienstanbieter-Designern maximale Flexibilität, um zu bestimmen, inwieweit sie sehr enge Töne unterscheiden können, da TAPI keine Annahmen darüber trifft, welche Tonbeschreibungen als identisch angesehen werden.