TSPI_lineGatherDigits-Funktion (tspi.h)
Die funktion TSPI_lineGatherDigits initiiert die gepufferte Sammlung von Ziffern für den angegebenen Aufruf. TAPI gibt einen Puffer an, in dem die Ziffern platziert werden sollen, und die maximale Anzahl der zu erfassenden Ziffern.
Syntax
LONG TSPIAPI TSPI_lineGatherDigits(
HDRVCALL hdCall,
DWORD dwEndToEndID,
DWORD dwDigitModes,
LPWSTR lpsDigits,
DWORD dwNumDigits,
LPCWSTR lpszTerminationDigits,
DWORD dwFirstDigitTimeout,
DWORD dwInterDigitTimeout
);
Parameter
hdCall
Das Handle des Dienstanbieters für den Aufruf, für den die Ziffernsammlung 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_GATHERDIGITS Nachricht gesendet wird. Der Dienstanbieter schließt diesen Bezeichner als einen der Parameter in der Nachricht ein.
dwDigitModes
Die zu überwachenden Ziffernmodi. Dieser Parameter verwendet eine oder mehrere der folgenden LINEDIGITMODE_ Konstanten.
lpsDigits
Ein Zeiger auf den Puffer, in dem erkannte Ziffern als Textzeichen gespeichert werden sollen. Der Dienstanbieter kann, aber nicht erforderlich, Ziffern nacheinander im Puffer platzieren, während sie erfasst werden. Wenn die LINE_GATHERDIGITS Nachricht gesendet wird, muss der Inhalt des Puffers vollständig sein. Wenn lpsDigits als NULL angegeben wird, wird die derzeit im Aufruf ausgeführte Ziffernsammlung abgebrochen, und der dwNumDigits-Parameter wird ignoriert. Andernfalls wird davon ausgegangen, dass lpsDigits Platz für dwNumDigits-Ziffern hat.
dwNumDigits
Die Anzahl der Ziffern, die erfasst werden sollen, bevor eine LINE_GATHERDIGITS Nachricht an TAPI gesendet wird. Der dwNumDigits-Parameter wird ignoriert, wenn lpsDigitsnull ist. Diese Funktion muss eine LINEERR_INVALPARAM zurückgeben, wenn dwNumDigits null ist.
lpszTerminationDigits
Zeiger auf eine Unicode-Zeichenfolge mit NULL-Terminierung mit Abschlussziffern als Textzeichen. Wenn eine der Ziffern in der Zeichenfolge erkannt wird, wird diese Beendigungsziffer an den Puffer angefügt, die Ziffernsammlung wird beendet, und die LINE_GATHERDIGITS Nachricht wird an TAPI gesendet.
Gültige Zeichen für den Pulsmodus sind "0" bis "9". Gültige Zeichen für den DTMF-Modus sind "0" bis "9", "A", "B", "C", "D", "*", "#". Wenn dieser Zeiger NULL ist oder auf eine leere Zeichenfolge zeigt, verhält sich die Funktion so, als ob keine Abschlussziffern angegeben wurden.
dwFirstDigitTimeout
Die Zeitdauer in Millisekunden, in der die erste Ziffer erwartet wird. Wenn die erste Ziffer in diesem Zeitrahmen nicht empfangen wird, wird die Ziffernsammlung beendet, und eine LINE_GATHERDIGITS Nachricht wird an TAPI gesendet. Ein einzelnes NULL-Zeichen wird in den Puffer geschrieben, was angibt, dass keine Ziffern empfangen wurden und die erste Ziffer mit timeout beendeten Ziffern gesammelt wurde. Die Zeilengerätefunktionen des Aufrufs geben den gültigen Bereich für diesen Parameter an oder geben an, dass Timeouts nicht unterstützt werden. Dieser Parameter wird nicht von TAPI überprüft, wenn diese Funktion aufgerufen wird.
dwInterDigitTimeout
Die maximale Zeitdauer in Millisekunden zwischen aufeinanderfolgenden Ziffern. Wenn in diesem Zeitraum keine Ziffer empfangen wird, wird die Ziffernsammlung beendet, und eine LINE_GATHERDIGITS Nachricht wird an TAPI gesendet. Ein einzelnes NULL-Zeichen wird in den Puffer geschrieben, was angibt, dass ein Interdigit-Timeout die Ziffernsammlung beendet hat. Die LINEDEVCAPS-Struktur muss den gültigen Bereich für diesen Parameter angeben oder angeben, dass Timeouts nicht unterstützt werden. Dieser Parameter wird nicht von TAPI überprüft, wenn diese Funktion aufgerufen wird.
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_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_NOMEM, LINEERR_INVALTIMEOUT, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM.
Hinweise
Der Dienstanbieter gibt LINEERR_INVALPARAM zurück, wenn der dwNumDigits-Parameter ungültig ist.
Diese Funktion gibt null (erfolg) zurück, 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) von einem Unicode-NULL-Zeichen gefolgt.
Die Ziffernsammlung kann auf folgende Weise beendet werden:
- Die angeforderte Anzahl von Ziffern wurde möglicherweise gesammelt.
- Eine der erkannten Ziffern entspricht einer Ziffer in szTerminationDigits , bevor die angegebene Anzahl von Ziffern erfasst wurde. Die erkannte Terminierungsziffer wird ebenfalls im Puffer platziert, und der Teilpuffer wird zurückgegeben.
- Eines der Timeouts läuft ab. 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 Teilpuffer zurückgegeben wird.
- Dieser Vorgang wird erneut aufgerufen, während die Sammlung ausgeführt wird. Die alte Sammlungssitzung wird beendet, und der Inhalt des alten Puffers ist nicht definiert. Um die Ziffernsammlung abzubrechen, ohne einen weiteren Vorgang zu initiieren, wird dieser Vorgang mit lpsDigits gleich NULL aufgerufen.
Die LINE_GATHERDIGITS Nachricht wird normalerweise gesendet, wenn der Ziffernpuffer gefüllt wird. Es wird auch gesendet, wenn Teilpuffer aufgrund von Timeouts oder übereinstimmenden Beendigungsziffern zurückgegeben werden oder wenn die Anforderung über eine andere TSPI_lineGatherDigits-Anforderung des Anrufs abgebrochen wird. Es kann jeweils nur eine Anforderung zum Sammeln von Ziffern aktiv sein. Der Dienstanbieter muss alle ausstehenden Sammelvorgänge mit einer LINE_GATHERDIGITS Nachricht beenden, wenn TSPI_lineGatherDigits aufgerufen wird.
Wenn der Vorgang, der einem Aufruf der TSPI_lineGatherDigits-Funktion zugeordnet ist, abgebrochen wird (durch einen nachfolgenden Aufruf der Funktion), kopiert der Dienstanbieter alle bis zu diesem Zeitpunkt gesammelten Ziffern in den puffer, der im ursprünglichen Aufruf angegeben ist.
TAPI kann TSPI_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 TAPI gesendet. Die Erkennung von gepufferten (Sammeln von Ziffern) und die Erkennung nicht gepufferter Ziffern können gleichzeitig für denselben Aufruf aktiviert werden.
Dem Dienstanbieter ist eine Gewisse Abweichung in der Qualität der Zeitsteuerung zulässig, die er für diese Funktion verwendet, einschließlich der Nicht-Ausführung von Timings. Die Qualität der Zeitsteuerung wird in LINEDEVCAPS, in den Membern dwGatherDigitsMinTimeout und dwGatherDigitsMaxTimeout gemeldet.
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_lineGatherDigits Anforderung von einer anderen zu unterscheiden.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | Windows |
| Kopfzeile | tspi.h |