lineGatherDigits 함수(tapi.h)

아티클
08/26/2023

lineGatherDigits 함수는 지정된 호출에서 버퍼링된 숫자 수집을 시작합니다. 애플리케이션은 수집할 숫자와 최대 자릿수를 배치할 버퍼를 지정합니다.

구문

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

매개 변수

hCall

숫자를 수집할 호출에 대한 핸들입니다. 애플리케이션은 호출의 소유자여야 합니다. hCall의 호출 상태는 모든 상태일 수 있습니다.

dwDigitModes

모니터링할 숫자 모드입니다. 이 매개 변수는 하나 이상의 LINEDIGITMODE_ 상수를 사용합니다.

lpsDigits

검색된 숫자를 텍스트 문자로 저장할 버퍼에 대한 포인터입니다. 숫자가 수집될 때 버퍼에 한 번에 하나씩 표시되지 않을 수 있습니다. 버퍼의 내용이 유효한 것으로 간주되어야 LINE_GATHERDIGITS 메시지가 수신된 후에만 가능합니다. lpsDigits가 NULL이면 호출에서 현재 진행 중인 숫자 수집이 종료되고 dwNumDigits가 무시됩니다. 그렇지 않으면 lpsDigits 는 dwNumDigits 숫자를 위한 공간을 갖는 것으로 간주됩니다.

dwNumDigits

LINE_GATHERDIGITS 메시지가 애플리케이션에 전송되기 전에 수집할 숫자 수입니다. lpsDigits가 NULL인 경우 dwNumDigits 매개 변수는 무시됩니다. dwNumDigits가 0이면 이 함수가 실패합니다.

lpszTerminationDigits

Null로 끝나는 종료 숫자 문자열을 텍스트 문자로 지정합니다. 문자열의 숫자 중 하나가 검색되면 해당 종료 숫자가 버퍼에 추가되고, 숫자 컬렉션이 종료되고, LINE_GATHERDIGITS 메시지가 애플리케이션으로 전송됩니다.

유효한 문자 목록은 dwDigitModes에 제공된 상수에 따라 달라집니다. 가능한 각 모드에 유효한 문자 목록은 LINEDIGITMODE_ 상수를 참조하세요.

이 포인터가 NULL이거나 빈 문자열을 가리키는 경우 함수는 종료 숫자가 제공되지 않은 것처럼 동작합니다.

dwFirstDigitTimeout

첫 번째 숫자가 예상되는 시간(밀리초)입니다. 이 기간에 첫 번째 숫자를 받지 못하면 숫자 컬렉션이 중단되고 애플리케이션에 LINE_GATHERDIGITS 메시지가 전송됩니다. 버퍼에는 숫자가 수신되지 않았고 첫 번째 자리 시간 제한 종료 숫자 수집을 나타내는 NULL 문자만 포함됩니다. 호출의 라인 디바이스 기능은 이 매개 변수의 유효한 범위를 지정하거나 시간 제한이 지원되지 않음을 나타냅니다.

dwInterDigitTimeout

연속된 숫자 사이의 최대 기간(밀리초)입니다. 이 기간에 숫자가 수신되지 않으면 숫자 컬렉션이 중단되고 애플리케이션에 LINE_GATHERDIGITS 메시지가 전송됩니다. 버퍼에는 이 시점까지 수집된 숫자와 NULL 문자만 포함되며, 이는 interdigit 시간 초과가 숫자 수집을 종료했음을 나타냅니다. 호출의 라인 디바이스 기능은 이 매개 변수의 유효한 범위를 지정하거나 시간 제한이 지원되지 않음을 나타냅니다.

반환 값

요청이 성공하면 0을 반환하고 오류가 발생하면 음수 오류 번호를 반환합니다. 가능한 반환 값은 다음과 같습니다.

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_NOTOWNER, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED.

설명

숫자 컬렉션은 요청된 숫자 수가 수집되면 종료됩니다. 또한 검색된 숫자 중 하나가 지정된 숫자 수를 수집하기 전에 szTerminationDigits 의 숫자와 일치할 때 종료됩니다. 검색된 종료 숫자도 버퍼에 배치되고 부분 버퍼가 반환됩니다.

시간 제한 중 하나가 만료되면 숫자 컬렉션을 취소하는 또 다른 방법이 발생합니다. 이 기간에 첫 번째 숫자를 받지 못하면 dwFirstDigitTimeout 이 만료됩니다. dwInterDigitTimout은 두 번째, 세 번째, (등) 숫자가 이전에 검색된 숫자로부터 해당 기간 내에 수신되지 않고 부분 버퍼가 반환되는 경우 만료됩니다.

숫자 컬렉션을 종료하는 네 번째 방법은 컬렉션이 진행 중인 동안 이 함수를 다시 호출하는 것입니다. 이전 컬렉션 세션이 종료되고, 해당 지점까지 수집된 모든 숫자가 이 함수에 대한 이전 호출에서 제공된 버퍼에 복사되고, LINE_GATHERDIGITS 메시지가 애플리케이션으로 전송될 때 버퍼가 전달됩니다. 숫자의 다른 수집을 시작하지 않고 숫자 수집을 종료하는 메커니즘은 nULL과 동일한 lpsDigits를 사용하여 이 함수를 호출하는 것입니다.

숫자 컬렉션이 종료된 경우가 아니라 숫자 컬렉션이 올바르게 시작된 경우 이 함수는 성공한 것으로 간주됩니다. 부분 버퍼가 반환되는 모든 경우 유효한 숫자(있는 경우) 뒤에 NULL 문자가 잇습니다.

이 함수는 모든 호출 상태에서 호출할 수 있지만 일반적으로 호출이 연결된 상태인 동안에만 숫자를 수집할 수 있습니다.

LINE_GATHERDIGITS 메시지는 요청을 시작한 애플리케이션으로만 전송됩니다. 시간 제한 또는 일치하는 종료 숫자로 인해 부분 버퍼가 반환되거나 호출 시 다른 lineGatherDigits 요청에 의해 요청이 취소될 때도 전송됩니다. 호출의 소유자인 모든 애플리케이션에서 지정된 시간에 하나의 gather-digits 요청만 호출에서 활성화할 수 있습니다. 작업의 비동기 동작을 감안할 때 여러 lineGatherDigits 요청을 연속해서 발급하는 애플리케이션은 나중에 여러 LINE_GATHERDIGITS 메시지를 수신할 수 있습니다. 이는 비정상적인 애플리케이션 동작이지만 애플리케이션은 이러한 메시지 수를 계산하여 취소 메시지가 이전 요청과 일치하도록 할 수 있습니다. 어쨌든 가장 최근의 요청만 유효한 것으로 간주해야 합니다.

참고 애플리케이션이 애플리케이션 메모리에 데이터를 다시 쓰는 비동기 작업을 호출하는 경우 애플리케이션은 LINE_REPLY 또는 LINE_GATHERDIGITS 메시지가 수신될 때까지 해당 메모리를 쓰기에 사용할 수 있도록 유지해야 합니다.

애플리케이션은 lineMonitorDigits 를 사용하여 버퍼링되지 않은 숫자 검색을 사용하거나 사용하지 않도록 설정할 수 있습니다. 이러한 방식으로 숫자가 검색될 때마다 LINE_MONITORDIGITS 메시지가 애플리케이션으로 전송됩니다. 버퍼링된 숫자와 버퍼링되지 않은 숫자 검색은 동일한 호출에 대해 동시에 사용하도록 설정할 수 있습니다.

전화 회의의 숫자 수집은 개별 참여 통화가 아닌 hConfCall에만 적용됩니다.

lineGatherDigits 함수를 사용하여 숫자를 수집하기 위한 이전 요청을 취소하는 경우 함수는 원래 함수 호출에 지정된 버퍼까지 수집된 모든 숫자를 복사합니다. 그런 다음 함수는 두 번째 호출의 lpszDigits 매개 변수가 NULL 또는 다른 주소를 지정하는지 여부에 관계없이 애플리케이션에 LINE_GATHERDIGITS 메시지를 보냅니다.