lineMonitorTones-Funktion (tapi.h)

Artikel
03/02/2024

Die lineMonitorTones-Funktion aktiviert und deaktiviert die Erkennung von Inbandtönen beim Aufruf. Jedes Mal, wenn ein angegebener Ton erkannt wird, wird eine Nachricht an die Anwendung gesendet.

Syntax

LONG lineMonitorTones(
  HCALL                   hCall,
  LPLINEMONITORTONE const lpToneList,
  DWORD                   dwNumEntries
);

Parameter

hCall

Handle an den Anruf, dessen Sprachkanaltöne überwacht werden sollen. Der Anrufstatus von hCall kann ein beliebiger Zustand mit Ausnahme des Leerlaufs sein.

lpToneList

Liste der zu überwachenden Töne. Dieser Parameter ist 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.

dwNumEntries

Anzahl der Einträge in lpToneList. Dieser Parameter wird ignoriert, wenn lpToneListNULL ist.

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_INVALCALLHANDLE, LINEERR_INVALCALLSTATE, LINEERR_INVALPOINTER, LINEERR_INVALTONE, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

Hinweise

Diese Funktion ist erfolgreich, wenn die Tonüberwachung ordnungsgemäß initiiert wurde, nicht wenn die Tonüberwachung beendet wurde. Die Tonüberwachung bleibt wirksam, bis sie explizit deaktiviert wird, indem lineMonitorTones mit einer anderen Tonliste (oder NULL) aufgerufen wird, bis der Aufruf in den Leerlauf übergeht oder wenn die Anwendung den Anrufhandle für den Anruf abordnet.

Obwohl diese Funktion in jedem Anrufzustand aufgerufen werden kann, können Töne in der Regel nur erkannt werden, wenn sich der Aufruf im verbundenen Zustand befindet. Die Tonerkennung erfordert in der Regel Rechenressourcen. Je nach 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 entsprechende Menge an Ressourcen für die Überwachung eines einzelnen dreifachen Frequenztons im Vergleich zu drei einzelnen Frequenztönen verbraucht werden. Wenn Ressourcen überlastet werden, wird der LINEERR_RESOURCEUNAVAIL-Fehler zurückgegeben.

Die lineMonitorTones-Funktion wird auch verwendet, um Stille zu erkennen. Stille wird als Ton mit einer Häufigkeit von 0 angegeben.

Die Überwachung von Tönen in einer Telefonkonferenz gilt nur für den hConfCall, nicht für die einzelnen teilnehmenden Anrufe.

Wenn der LINEERR_INVALPOINTER Fehlerwert zurückgegeben wird, ist der angegebene lpToneList-Parameter ungültig, oder der vom dwNumEntries-Parameter angegebene Wert ist zu groß.