TSPI_lineMonitorTones 함수(tspi.h)

아티클
08/26/2023

TSPI_lineMonitorTones 함수는 호출에서 인밴드 톤 검색을 활성화하고 사용하지 않도록 설정합니다. 지정된 톤이 검색될 때마다 TAPI를 통해 클라이언트 애플리케이션에 메시지가 전송됩니다.

구문

LONG TSPIAPI TSPI_lineMonitorTones(
  HDRVCALL                hdCall,
  DWORD                   dwToneListID,
  LPLINEMONITORTONE const lpToneList,
  DWORD                   dwNumEntries
);

매개 변수

hdCall

톤 감지를 수행할 호출에 대한 핸들입니다. hdCall의 호출 상태는 유휴 상태를 제외한 모든 상태일 수 있습니다.

dwToneListID

이 톤 목록의 고유 식별자입니다. 여러 톤 목록은 한 번에 뛰어난 수 있습니다. 서비스 공급자는 동일한 dwToneListID 를 가진 모든 이전 목록을 새 톤 목록으로 바꿔야 합니다. lpToneList가 NULL이면 dwToneListID가 있는 톤 목록이 삭제됩니다. 어떤 경우든 다른 dwToneListID가 있는 다른 톤 목록은 변경되지 않은 상태로 유지됩니다.

lpToneList

모니터링할 톤 목록으로 LINEMONITORTONE 형식입니다. 이 목록의 각 톤에는 톤 감지를 보고하기 위해 목록에서 개별 톤을 식별하는 데 사용되는 애플리케이션 정의 태그 필드가 있습니다. 진행 중인 톤 모니터링은 lpToneList에 대해 NULL 또는 다른 톤 목록을 사용하여 이 작업을 호출하여 취소되거나 변경됩니다. 서비스 공급자는 단순히 포인터를 애플리케이션 메모리에 유지하는 대신 나중에 참조하기 위해 톤 목록을 자체 메모리에 복사해야 합니다.

dwNumEntries

lpToneList의 항목 수입니다. lpToneList가 NULL인 경우 dwNumEntries 매개 변수는 무시됩니다. TAPI는 이 함수가 호출되면 이 매개 변수의 유효성을 검사하지 않습니다.

반환 값

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

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALTONE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_INVALPOINTER.

설명

이 함수는 톤 모니터링이 종료될 때가 아니라 톤 모니터링이 올바르게 시작될 때 0(성공)을 반환합니다. 미디어 모니터링과 마찬가지로 동일한 dwToneListID 및 다른 톤 목록(또는 NULL 톤 목록)을 사용하여 TSPI_lineMonitorTones 호출하거나 통화가 유휴 상태로 전환될 때까지 해당 톤 목록이 명시적으로 비활성화될 때까지 톤 모니터링이 지정된 톤 목록에 계속 적용됩니다.

유휴 상태를 제외한 모든 호출 상태에서 이 함수를 호출할 수 있지만 일반적으로 통화가 연결된 상태일 때만 톤을 검색할 수 있습니다. 톤 검색에는 일반적으로 계산 리소스가 필요합니다. 이러한 리소스에 대해 경쟁하는 서비스 공급자 및 기타 활동에 따라 검색할 수 있는 톤 수는 시간에 따라 달라질 수 있습니다. 또한 단일 3중 주파수 톤과 3개의 단일 빈도 톤을 모니터링하는 데 동일한 양의 리소스를 사용할 수 있습니다. 리소스가 과도하게 커밋되면 서비스 공급자는 LINEERR_RESOURCEUNAVAIL 반환합니다.

서비스 공급자는 모든 톤 목록의 모든 톤을 동시에 모니터링합니다. 톤이 감지되면 각 톤 목록에서 일치하는 각 톤은 LINE_MONITORTONE 메시지를 사용하여 개별적으로 보고됩니다. 각 톤 보고서에는 톤 목록 식별자와 애플리케이션별 태그가 모두 포함됩니다. 일부 서비스 공급자는 매우 가까운 톤을 구분하지 못할 수 있으므로 설명이 엄격하게 동일하지 않은 톤에 대해서도 여러 일치 항목이 보고될 수 있습니다.

참고TSPI_lineMonitorTones 침묵을 감지하는 데도 사용됩니다. 무음은 모든 빈도가 없는 톤으로 지정됩니다.

TAPI 수준의 해당 함수에는 dwToneListID 매개 변수가 포함되지 않습니다. TSPI 인터페이스에 이 매개 변수를 포함하면 TAPI는 모든 애플리케이션의 모든 톤 모니터링 목록의 공용 구조체를 서비스 공급자로 전달할 수 있지만 애플리케이션에 따라 톤 검색 이벤트를 필터링하고 전달하는 기능을 유지할 수 있습니다. 이를 통해 서비스 공급자 디자이너는 매우 가까운 톤을 구분할 수 있는 정도를 결정할 수 있는 최대 유연성을 제공합니다. TAPI는 동일한 톤 설명으로 간주되는 톤 설명을 가정하지 않으므로 매우 가까운 톤을 구분할 수 있습니다.