lineGenerateDigits-Funktion (tapi.h)

Artikel
08/26/2023

Die lineGenerateDigits-Funktion initiiert die Generierung der angegebenen Ziffern für den angegebenen Aufruf als Inbandtöne mithilfe des angegebenen Signalisierungsmodus. Wenn Sie diese Funktion mit einem NULL-Wert für lpszDigits aufrufen, wird jede derzeit laufende Zifferngenerierung abgebrochen. Das Aufrufen von lineGenerateDigits oder lineGenerateTone während der Zifferngenerierung bricht die aktuelle Ziffern- oder Tongenerierung ab und initiiert die Generierung der zuletzt angegebenen Ziffern oder Destons.

Syntax

LONG lineGenerateDigits(
  HCALL  hCall,
  DWORD  dwDigitMode,
  LPCSTR lpszDigits,
  DWORD  dwDuration
);

Parameter

hCall

Handle für den Aufruf. Die Anwendung muss ein Besitzer des Anrufs sein. Der Aufrufstatus von hCall kann ein beliebiger Zustand sein. TAPI erzwingt keine Aufrufzustandsanforderungen, aber einige Tapi-Dienstanbieter können verlangen, dass sich der hCall im LINECALLSTATE_CONNECTED Zustand befindet.

dwDigitMode

Format, das zum Signalisieren dieser Ziffern verwendet werden soll. Beachten Sie, dass dwDigitMode nur ein einzelnes Flag festlegen kann. Dieser Parameter verwendet eine der LINEDIGITMODE_ Konstanten.

lpszDigits

Zeiger auf einen Zeichenpuffer mit NULL-Beendigung, der die zu generierenden Ziffern enthält. Gültige Zeichen sind diejenigen, die für die in dwDigitModesbereitgestellten LINEDIGITMODE_ Konstanten angegeben sind.

Darüber hinaus ist das Komma (,) auch ein gültiges Zeichen. Ein Komma fügt eine zusätzliche Verzögerung zwischen der Signalisierung der vorherigen und der nächsten Ziffer ein, die es trennt. Die Dauer dieser Pause wird von der Konfiguration definiert, und die Zeilengerätefunktionen geben diese Dauer an. Zum Einfügen längerer Pausen können mehrere Kommas verwendet werden. Ungültige Ziffern werden während der Generierung ignoriert, anstatt als Fehler gemeldet zu werden.

Das Ausrufezeichen (!) ist ein gültiges Zeichen. Dieses Zeichen verursacht einen Hookflash-Vorgang, wie für wählbare Adressen beschrieben.

dwDuration

Sowohl die Dauer der DTMF-Ziffern als auch des Pulss und des DTMF-Zwischenstellenabstands in Millisekunden. Der Wert 0 verwendet einen Standardwert. Der dwDuration-Parameter muss innerhalb des durch MinDialParams und MaxDialParams in LINEDEVCAPS angegebenen Bereichs liegen. Liegt der Bereich außerhalb des Bereichs, wird der tatsächliche Wert auf den nächsten Wert im Bereich festgelegt.

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_INVALDIGITMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Hinweise

Die lineGenerateDigits-Funktion gilt als erfolgreich abgeschlossen, wenn die Zifferngenerierung erfolgreich initiiert wurde, nicht, wenn alle Ziffern generiert wurden. Im Gegensatz zu lineDial, das Ziffern netzwerkabhängig wählt, garantiert lineGenerateDigits , dass die Ziffern über den Sprachkanal mithilfe von DTMF- oder Hookswitch-Wählimpulsen als Inbandtöne über den Sprachkanal erzeugt werden. Die lineGenerateDigits-Funktion eignet sich in der Regel nicht für Anrufe oder Wählvorgänge. Es ist für die End-to-End-Signalisierung über einen eingerichteten Anruf vorgesehen.

Nachdem alle Ziffern in lpszDigits generiert wurden oder nachdem die Zifferngenerierung abgebrochen oder abgebrochen wurde, 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. Die Zifferngenerierung bei einem Anruf wird abgebrochen, indem entweder eine weitere Anforderung zur Zifferngenerierung oder eine Anforderung zur Tongenerierung initiiert wird. Um die aktuelle Zifferngenerierung abzubrechen, kann die Anwendung lineGenerateDigits aufrufen und NULL für den lpszDigits-Parameter angeben.

Je nach Dienstanbieter und Hardware kann die Anwendung die selbst generierten Ziffern überwachen. Wenn dies nicht gewünscht ist, kann die Anwendung die Ziffernüberwachung beim Generieren von Ziffern deaktivieren.