TSPI_lineGenerateTone-Funktion (tspi.h)

Artikel
08/26/2023

Die TSPI_lineGenerateTone-Funktion generiert den angegebenen Tonband über den angegebenen Aufruf. Wenn Sie diese Funktion mit einer Null für dwToneMode aufrufen, wird jede tonale Generierung abgebrochen, die derzeit für den angegebenen Aufruf ausgeführt wird. Durch das Aufrufen TSPI_lineGenerateTone oder TSPI_lineGenerateDigits während der Tongenerierung wird die aktuelle Ton- oder Zifferngenerierung in Bearbeitung abgebrochen und die Generierung des neu angegebenen Tones oder der neu angegebenen Ziffern initiiert.

Syntax

LONG TSPIAPI TSPI_lineGenerateTone(
  HDRVCALL                 hdCall,
  DWORD                    dwEndToEndID,
  DWORD                    dwToneMode,
  DWORD                    dwDuration,
  DWORD                    dwNumTones,
  LPLINEGENERATETONE const lpTones
);

Parameter

hdCall

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

dwEndToEndID

Ein eindeutiger, nicht interpretierter Bezeichner der Anforderung für die gesamte Lebensdauer, d. h. bis die übereinstimmende LINE_GENERATE Nachricht gesendet wird. Der Dienstanbieter schließt diesen Bezeichner als einen der Parameter in der Nachricht ein.

dwToneMode

Definiert den zu generierenden Ton. Töne können entweder standard oder benutzerdefiniert sein. Ein benutzerdefinierter Ton besteht aus einer Reihe beliebiger Frequenzen. Eine kleine Anzahl von Standardtönen ist vordefiniert. Die Dauer des Tons wird von dwDuration sowohl für Standardtöne als auch für benutzerdefinierte Töne angegeben. Wenn dwToneMode auf 0 festgelegt ist, wird jede laufende Ziffern- oder Tongenerierung abgebrochen. Dieser Parameter verwendet nur eine der LINETONEMODE_ Konstanten.

dwDuration

Die Dauer in Millisekunden, während derer der Ton aufrechterhalten wird. Der Wert 0 für dwDuration verwendet eine Standarddauer für den angegebenen Ton. Die Standardwerte lauten wie folgt:

BENUTZERDEFINIERT: unendlich

RINGBACK: unendlich

BUSY: unendlich

BEEP: unendlich

ABRECHNUNG: fix (einzelzyklus)

Dieser Parameter wird nicht von TAPI überprüft, wenn diese Funktion aufgerufen wird.

dwNumTones

Die Anzahl der Einträge im lpTones-Array . Dieser Parameter wird ignoriert, wenn dwToneMode nicht gleich LINETONEMODE_CUSTOM ist.

lpTones

Ein Zeiger auf ein LINEGENERATETONE-Array , das die Komponenten des Tones angibt. Dieser Parameter wird für nicht angepasste Töne ignoriert. Wenn lpTones ein mehrstufiger Ton ist, werden die verschiedenen Töne gleichzeitig wiedergegeben.

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_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALTONEMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALTONE, LINEERR_RESOURCEUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Hinweise

TSPI_lineGenerateTone gibt null (erfolg) zurück, wenn die Tongenerierung erfolgreich initiiert wurde. nicht, wenn die Tongenerierung abgeschlossen ist. Die Funktion ermöglicht die Inbandgenerierung mehrerer vordefinierter Töne, z. B. Ringback, Busy-Töne und Signalton. Es ermöglicht auch die Herstellung von benutzerdefinierten Tönen, indem deren Komponentenfrequenzen, Rhythmus und Lautstärke angegeben werden, wenn dies vom Dienstanbieter unterstützt wird. Da diese Töne als Inbandtöne generiert werden, muss sich der Anruf in der Regel im verbundenen Zustand befinden, damit die Tongenerierung effektiv ist. Wenn die Tongenerierung abgeschlossen oder die Tongenerierung abgebrochen wird, wird eine LINE_GENERATE Nachricht an TAPI gesendet.

Hinweis Pro Anruf darf nur eine Inbandgenerierungsanforderung (Tongenerierung oder Zifferngenerierung) ausgeführt werden. Dies impliziert, dass, wenn die Tongenerierung derzeit bei einem Anruf ausgeführt wird, durch den Aufruf von TSPI_lineGenerateDigits oder TSPI_lineGenerateTone die Tongenerierung abgebrochen wird. Der Dienstanbieter muss beim Aufrufen einer nachfolgenden TSPI_lineGenerateDigits - oder TSPI_lineGenerateTone-Funktion alle in Bearbeitung geschalteten Töne beenden.

Die entsprechende Funktion auf TAPI-Ebene enthält den formalen Parameter dwEndToEndID nicht. Auf dieser Ebene gibt es keine End-to-End-Markierung. TAPI verwendet end-to-End-Markierungen auf TSPI-Ebene, um eine TSPI_lineGenerateTone Anforderung von einer anderen zu unterscheiden.