TSPI_lineGatherDigits 함수(tspi.h)
TSPI_lineGatherDigits 함수는 지정된 호출에서 버퍼링된 숫자 수집을 시작합니다. TAPI는 수집할 숫자와 최대 자릿수를 배치할 버퍼를 지정합니다.
구문
LONG TSPIAPI TSPI_lineGatherDigits(
HDRVCALL hdCall,
DWORD dwEndToEndID,
DWORD dwDigitModes,
LPWSTR lpsDigits,
DWORD dwNumDigits,
LPCWSTR lpszTerminationDigits,
DWORD dwFirstDigitTimeout,
DWORD dwInterDigitTimeout
);
매개 변수
hdCall
숫자 수집을 수행할 호출에 대한 서비스 공급자의 핸들입니다. hdCall의 호출 상태는 유휴 상태를 제외한 모든 상태일 수 있습니다.
dwEndToEndID
전체 수명, 즉 일치하는 LINE_GATHERDIGITS 메시지가 전송될 때까지 요청의 고유하고 해석되지 않은 식별자입니다. 서비스 공급자는 메시지의 매개 변수 중 하나로 이 식별자를 포함합니다.
dwDigitModes
모니터링할 숫자 모드입니다. 이 매개 변수는 다음 LINEDIGITMODE_ 상수 중 하나 이상을 사용합니다.
| 값 | 의미 |
|---|---|
|
회전 펄스 시퀀스를 사용한 결과인 가청 클릭으로 숫자를 감지합니다. 펄스 모드의 유효한 숫자는 '0'~'9'입니다. |
|
숫자를 DTMF 톤으로 검색합니다. DTMF 모드의 유효한 숫자는 '0'~'9', 'A', 'B', 'C', 'D', '*', '#'입니다. |
lpsDigits
검색된 숫자를 텍스트 문자로 저장할 버퍼에 대한 포인터입니다. 서비스 공급자는 수집될 때 버퍼에 숫자를 한 번에 하나씩 배치할 수 있지만 필요하지는 않습니다. LINE_GATHERDIGITS 메시지가 전송되면 버퍼의 내용이 완료되어야 합니다. lpsDigits가 NULL로 지정되면 호출에서 현재 진행 중인 숫자 수집이 취소되고 dwNumDigits 매개 변수가 무시됩니다. 그렇지 않으면 lpsDigits 는 dwNumDigits 숫자를 위한 공간을 갖는 것으로 간주됩니다.
dwNumDigits
LINE_GATHERDIGITS 메시지가 TAPI로 전송되기 전에 수집할 숫자 수입니다. lpsDigits가 NULL인 경우 dwNumDigits 매개 변수는 무시됩니다. dwNumDigits가 0인 경우 이 함수는 LINEERR_INVALPARAM 반환해야 합니다.
lpszTerminationDigits
종료 숫자의 null로 끝나는 유니코드 문자열을 텍스트 문자로 가리키는 포인터입니다. 문자열의 숫자 중 하나가 검색되면 해당 종료 숫자가 버퍼에 추가되고, 숫자 컬렉션이 종료되고, LINE_GATHERDIGITS 메시지가 TAPI로 전송됩니다.
펄스 모드의 유효한 문자는 '0'~'9'입니다. DTMF 모드의 유효한 문자는 '0'~'9', 'A', 'B', 'C', 'D', '*', '#'입니다. 이 포인터가 NULL이거나 빈 문자열을 가리키는 경우 함수는 종료 숫자가 제공되지 않은 것처럼 동작합니다.
dwFirstDigitTimeout
첫 번째 숫자가 예상되는 시간(밀리초)입니다. 이 기간에 첫 번째 숫자를 받지 못하면 숫자 컬렉션이 종료되고 LINE_GATHERDIGITS 메시지가 TAPI로 전송됩니다. 단일 NULL 문자가 버퍼에 기록되어 수신된 숫자가 없고 첫 번째 숫자 제한 시간이 종료된 숫자 수집을 나타냅니다. 호출의 줄 디바이스 기능은 이 매개 변수의 유효한 범위를 지정하거나 시간 제한이 지원되지 않음을 나타냅니다. 이 함수가 호출될 때 TAPI에서 이 매개 변수의 유효성을 검사하지 않습니다.
dwInterDigitTimeout
연속된 숫자 사이의 최대 기간(밀리초)입니다. 이 기간에 숫자가 수신되지 않으면 숫자 컬렉션이 종료되고 LINE_GATHERDIGITS 메시지가 TAPI로 전송됩니다. 단일 NULL 문자가 버퍼에 기록되어 interdigit 시간 제한이 숫자 수집을 종료했음을 나타냅니다. LINEDEVCAPS 구조체는 이 매개 변수에 유효한 범위를 지정하거나 시간 제한이 지원되지 않음을 나타내야 합니다. 이 함수가 호출될 때 TAPI에서 이 매개 변수의 유효성을 검사하지 않습니다.
반환 값
함수가 성공하면 0을 반환하고 오류가 발생하면 오류 번호를 반환합니다. 가능한 반환 값은 다음과 같습니다.
LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_NOMEM, LINEERR_INVALTIMEOUT, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM.
설명
dwNumDigits 매개 변수가 잘못된 경우 서비스 공급자는 LINEERR_INVALPARAM 반환합니다.
이 함수는 숫자 컬렉션이 올바르게 시작되면 0(성공)을 반환합니다. 숫자 컬렉션이 종료된 경우는 아닙니다. 부분 버퍼가 반환되는 모든 경우 유효한 숫자(있는 경우) 뒤에 유니코드 NULL 문자가 잇습니다.
숫자 컬렉션은 다음과 같은 방법으로 종료할 수 있습니다.
- 요청된 숫자 수가 수집되었을 수 있습니다.
- 검색된 숫자 중 하나는 지정된 숫자 수를 수집하기 전에 szTerminationDigits 의 숫자와 일치합니다. 검색된 종료 숫자도 버퍼에 배치되고 부분 버퍼가 반환됩니다.
- 시간 제한 중 하나가 만료됩니다. 이 기간에 첫 번째 숫자를 받지 못하면 dwFirstDigitTimeout 이 만료됩니다. dwInterDigitTimout은 두 번째, 세 번째, (등) 숫자가 이전에 검색된 숫자로부터 해당 기간 내에 수신되지 않고 부분 버퍼가 반환되는 경우 만료됩니다.
- 컬렉션이 진행 중인 동안 이 작업을 다시 호출합니다. 이전 컬렉션 세션이 종료되고 이전 버퍼의 내용이 정의되지 않았습니다. 다른 작업을 시작하지 않고 숫자 수집을 취소하기 위해 이 작업은 nULL과 동일한 lpsDigits 를 사용하여 호출됩니다.
LINE_GATHERDIGITS 메시지는 일반적으로 숫자 버퍼가 채워질 때 전송됩니다. 시간 제한 또는 일치하는 종료 숫자로 인해 부분 버퍼가 반환되거나 호출 시 다른 TSPI_lineGatherDigits 요청을 통해 요청이 취소될 때도 전송됩니다. 한 번에 하나의 수집 숫자 요청만 활성화할 수 있습니다. 서비스 공급자는 TSPI_lineGatherDigits 호출 할 때 LINE_GATHERDIGITS 메시지를 사용하여 미해결 수집 작업을 종료해야 합니다.
TSPI_lineGatherDigits 함수 호출과 관련된 작업이 취소되면(함수에 대한 후속 호출에 의해) 서비스 공급자는 원래 호출에 지정된 버퍼까지 수집된 모든 숫자를 복사합니다.
TAPI는 TSPI_lineMonitorDigits 사용하여 버퍼되지 않은 숫자 검색을 사용하거나 사용하지 않도록 설정할 수 있습니다. 이러한 방식으로 숫자가 검색될 때마다 LINE_MONITORDIGITS 메시지가 TAPI로 전송됩니다. 버퍼링된(수집 숫자) 및 버퍼링되지 않은 숫자 검색을 동일한 호출에 동시에 사용하도록 설정할 수 있습니다.
서비스 공급자는 타이밍을 전혀 수행하지 않는 것을 포함하여 이 함수에 사용하는 타이밍의 품질에 약간의 변화를 허용합니다. 타이밍의 품질은 DwGatherDigitsMinTimeout 및 dwGatherDigitsMaxTimeout 멤버의 LINEDEVCAPS에서 보고됩니다.
TAPI 수준의 해당 함수에는 공식 매개 변수 dwEndToEndID가 포함되지 않습니다. 이 수준에서는 종단 간 표시가 없습니다. TAPI는 TSPI 수준에서 엔드 투 엔드 표시를 사용하여 한 TSPI_lineGatherDigits 요청을 다른 요청 과 구분합니다.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 대상 플랫폼 | Windows |
| 헤더 | tspi.h |