lineGenerateTone-Funktion (tapi.h)

Artikel
03/04/2024

Die lineGenerateTone-Funktion generiert den angegebenen Inbandton über den angegebenen Aufruf. Wenn Sie diese Funktion mit einer Null für dwToneMode aufrufen, wird die derzeit für den angegebenen Aufruf ausgeführte Tongenerierung abgebrochen. Das Aufrufen von lineGenerateTone oder lineGenerateDigits während der Tongenerierung bricht die aktuelle Tongenerierung oder Zifferngenerierung ab und initiiert die Generierung des neu angegebenen Tones oder der neu angegebenen Ziffern.

Syntax

LONG lineGenerateTone(
  HCALL                    hCall,
  DWORD                    dwToneMode,
  DWORD                    dwDuration,
  DWORD                    dwNumTones,
  LPLINEGENERATETONE const lpTones
);

Parameter

hCall

Handle mit dem Aufruf, für den ein Ton generiert werden soll. Die Anwendung muss ein Besitzer des Anrufs sein. Der Aufrufstatus von hCall kann ein beliebiger Zustand sein.

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 mit dwDuration sowohl für Standardtöne als auch für benutzerdefinierte Töne angegeben. Für den dwToneMode-Parameter kann nur ein Bit festgelegt sein. Wenn keine Bits festgelegt sind (der Wert 0 wird übergeben), wird die Tongenerierung abgebrochen. Dieser Parameter verwendet eine der LINETONEMODE_ Konstanten.

dwDuration

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

CUSTOM: Der Ton bleibt erhalten, bis er abgeschaltet wird, in der Regel durch Benutzerinteraktionen oder ein Gerätetimeout.

RINGBACK: Der Ton bleibt erhalten, bis er abgeschaltet wird, in der Regel durch Benutzerinteraktionen oder ein Gerätetimeout.

BESCHÄFTIGT: Der Ton bleibt erhalten, bis er abgeschaltet wird, in der Regel durch Benutzerinteraktionen oder ein Timeout der Ausrüstung.

BEEP: Der Ton bleibt erhalten, bis er abgeschaltet wird, in der Regel durch Benutzerinteraktion oder ein Gerätetimeout.

ABRECHNUNG: Behoben (einzeler Zyklus).

dwNumTones

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

lpTones

Zeiger auf ein LINEGENERATETONE-Array , das die Komponenten des Tones angibt. Dieser Parameter wird für Standardtöne LINETONEMODE_ Konstanten ignoriert, z. B. LINETONEMODE_BUSY. Wenn lpTones ein mehrstufiger Ton ist, werden die verschiedenen Töne gleichzeitig wiedergegeben.

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

Hinweise

Die lineGenerateTone-Funktion gilt als erfolgreich abgeschlossen, wenn die Tongenerierung erfolgreich initiiert wurde, nicht nach Abschluss der Tongenerierung. 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. 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 Generierung des Tones abgeschlossen ist oder die Tongenerierung abgebrochen wird, wird eine LINE_GENERATE Nachricht an die Anwendung gesendet.

Nur eine Inband-Generierungsanforderung (Tongenerierung oder Zifferngenerierung) darf pro Anruf in allen Anwendungen ausgeführt werden, die Besitzer des Anrufs sind. Dies impliziert, dass, wenn die Tongenerierung derzeit bei einem Anruf ausgeführt wird, durch den Aufruf von lineGenerateDigits die Tongenerierung abgebrochen wird.

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