lineGatherDigits-Funktion (tapi.h)

Artikel
08/26/2023

Die lineGatherDigits-Funktion initiiert die gepufferte Erfassung von Ziffern für den angegebenen Aufruf. Die Anwendung gibt einen Puffer an, in dem die Ziffern und die maximale Anzahl der zu sammelnden Ziffern platziert werden sollen.

Syntax

LONG lineGatherDigits(
  HCALL  hCall,
  DWORD  dwDigitModes,
  LPSTR  lpsDigits,
  DWORD  dwNumDigits,
  LPCSTR lpszTerminationDigits,
  DWORD  dwFirstDigitTimeout,
  DWORD  dwInterDigitTimeout
);

Parameter

hCall

Handle an den Aufruf, für den Ziffern erfasst werden sollen. Die Anwendung muss besitzer des Aufrufs sein. Der Anrufstatus von hCall kann ein beliebiger Zustand sein.

dwDigitModes

Zu überwachende Ziffernmodi. Dieser Parameter verwendet mindestens eine der LINEDIGITMODE_ Konstanten.

lpsDigits

Zeiger auf den Puffer, in dem erkannte Ziffern als Textzeichen gespeichert werden sollen. Ziffern werden möglicherweise nicht einzeln im Puffer angezeigt, da sie gesammelt werden. Erst nachdem eine LINE_GATHERDIGITS Nachricht empfangen wurde, sollte davon ausgegangen werden, dass der Inhalt des Puffers gültig ist. Wenn lpsDigitsNULL ist, wird die derzeit für den Aufruf laufende Ziffernsammlung beendet, und dwNumDigits wird ignoriert. Andernfalls wird davon ausgegangen, dass lpsDigits Platz für dwNumDigits-Ziffern hat.

dwNumDigits

Anzahl der Ziffern, die erfasst werden müssen, bevor eine LINE_GATHERDIGITS Nachricht an die Anwendung gesendet wird. Der dwNumDigits-Parameter wird ignoriert, wenn lpsDigitsNULL ist. Diese Funktion schlägt fehl, wenn dwNumDigits null ist.

lpszTerminationDigits

Null-endende Zeichenfolge von Abschlussziffern als Textzeichen. Wenn eine der Ziffern in der Zeichenfolge erkannt wird, wird diese Abschlussziffer an den Puffer angefügt, die Ziffernsammlung wird beendet, und die LINE_GATHERDIGITS Nachricht wird an die Anwendung gesendet.

Die Liste der gültigen Zeichen ist von der in dwDigitModes bereitgestellten Konstante abhängig. Eine Liste der gültigen Zeichen für jeden möglichen Modus finden Sie unter LINEDIGITMODE_ Konstanten.

Wenn dieser Zeiger NULL ist oder auf eine leere Zeichenfolge verweist, verhält sich die Funktion so, als ob keine Abschlussziffern angegeben wurden.

dwFirstDigitTimeout

Zeitdauer in Millisekunden, in der die erste Ziffer erwartet wird. Wenn die erste Ziffer in diesem Zeitraum nicht empfangen wird, wird die Ziffernsammlung abgebrochen und eine LINE_GATHERDIGITS Nachricht an die Anwendung gesendet. Der Puffer enthält nur das NULL-Zeichen , das angibt, dass keine Ziffern empfangen wurden, und die Erfassung beendeter Ziffern für das erste Zifferntimeout. Die Line-Device-Funktionen des Aufrufs geben den gültigen Bereich für diesen Parameter an oder geben an, dass Timeouts nicht unterstützt werden.

dwInterDigitTimeout

Maximale Zeitdauer in Millisekunden zwischen aufeinanderfolgenden Ziffern. Wenn in diesem Zeitrahmen keine Ziffer empfangen wird, wird die Ziffernsammlung abgebrochen und eine LINE_GATHERDIGITS Nachricht an die Anwendung gesendet. Der Puffer enthält nur die bis zu diesem Punkt gesammelten Ziffern, gefolgt von einem NULL-Zeichen , das angibt, dass ein Interdigit-Timeout die Ziffernsammlung beendet hat. Die Line-Device-Funktionen des Aufrufs geben den gültigen Bereich für diesen Parameter an oder geben an, dass Timeouts nicht unterstützt werden.

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_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_NOTOWNER, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED.

Hinweise

Die Ziffernsammlung wird beendet, wenn die angeforderte Anzahl von Ziffern erfasst wurde. Sie wird auch beendet, wenn eine der erkannten Ziffern mit einer Ziffer in szTerminationDigits übereinstimmt, bevor die angegebene Anzahl von Ziffern erfasst wurde. Die erkannte Abschlussziffer wird ebenfalls im Puffer platziert, und der Teilpuffer wird zurückgegeben.

Eine andere Möglichkeit zum Abbrechen der Ziffernsammlung besteht, wenn eines der Timeouts abläuft. DwFirstDigitTimeout läuft ab, wenn die erste Ziffer in diesem Zeitraum nicht empfangen wird. DwInterDigitTimout läuft ab, wenn die zweite, dritte (usw.) Ziffer nicht innerhalb dieses Zeitraums von der zuvor erkannten Ziffer empfangen wird und ein teilweiser Puffer zurückgegeben wird.

Eine vierte Methode zum Beenden der Ziffernsammlung ist das erneute Aufrufen dieser Funktion, während die Sammlung ausgeführt wird. Die alte Sammlungssitzung wird beendet, alle bis zu diesem Zeitpunkt gesammelten Ziffern werden in den Puffer kopiert, der vom vorherigen Aufruf dieser Funktion bereitgestellt wurde, und der Puffer wird übermittelt, wenn die LINE_GATHERDIGITS Nachricht an die Anwendung gesendet wird. Der Mechanismus zum Beenden der Ziffernsammlung, ohne eine weitere Erfassung der Ziffern zu initiieren, besteht darin, diese Funktion mit lpsDigits gleich NULL aufzurufen.

Diese Funktion gilt als erfolgreich, wenn die Ziffernsammlung ordnungsgemäß initiiert wurde, nicht, wenn die Ziffernsammlung beendet wurde. In allen Fällen, in denen ein partieller Puffer zurückgegeben wird, werden gültige Ziffern (sofern vorhanden) durch ein NULL-Zeichen gefolgt.

Obwohl diese Funktion in jedem Aufrufzustand aufgerufen werden kann, können Ziffern in der Regel nur erfasst werden, wenn sich der Aufruf im verbundenen Zustand befindet.

Die Nachricht LINE_GATHERDIGITS wird nur an die Anwendung gesendet, die die Anforderung initiiert hat. Es wird auch gesendet, wenn Teilpuffer aufgrund von Timeouts oder übereinstimmenden Abschlussziffern zurückgegeben werden oder wenn die Anforderung von einer anderen lineGatherDigits-Anforderung für den Aufruf abgebrochen wird. Für alle Anwendungen, die Besitzer des Anrufs sind, kann nur eine Anforderung für die Erfassung von Ziffern zu einem bestimmten Zeitpunkt aktiv sein. Aufgrund des asynchronen Verhaltens des Vorgangs kann eine Anwendung, die mehrere lineGatherDigits-Anforderungen in schneller Folge ausgibt, dies tun und später mehrere LINE_GATHERDIGITS-Nachrichten empfangen. Obwohl dies ein ungewöhnliches Anwendungsverhalten wäre, kann die Anwendung die Anzahl dieser Nachrichten zählen, damit abgesagte Nachrichten mit den früheren Anforderungen abgeglichen werden können. In jedem Fall sollte nur die letzte Anforderung als gültig angenommen werden.

Hinweis Wenn eine Anwendung einen asynchronen Vorgang aufruft, der Daten zurück in den Anwendungsspeicher schreibt, muss die Anwendung diesen Arbeitsspeicher zum Schreiben zur Verfügung halten, bis eine LINE_REPLY oder LINE_GATHERDIGITS Nachricht empfangen wird.

Eine Anwendung kann lineMonitorDigits verwenden, um die Erkennung nicht gepufferter Ziffern zu aktivieren oder zu deaktivieren. Jedes Mal, wenn eine Ziffer auf diese Weise erkannt wird, wird eine LINE_MONITORDIGITS Nachricht an die Anwendung gesendet. Die Erkennung gepufferter und nicht gepufferter Ziffern kann gleichzeitig für denselben Aufruf aktiviert werden.

Das Sammeln von Ziffern bei einer Telefonkonferenz gilt nur für den hConfCall, nicht für die einzelnen teilnehmenden Anrufe.

Wenn die lineGatherDigits-Funktion verwendet wird, um eine vorherige Anforderung zum Sammeln von Ziffern abzubrechen, kopiert die Funktion alle bis zu diesem Zeitpunkt gesammelten Ziffern in den Puffer, der im ursprünglichen Funktionsaufruf angegeben ist. Die Funktion sendet dann eine LINE_GATHERDIGITS Nachricht an die Anwendung, unabhängig davon, ob der lpszDigits-Parameter im zweiten Aufruf eine NULL-Adresse oder eine andere Adresse angibt.