lineGenerateTone 함수(tapi.h)

아티클
03/02/2024

lineGenerateTone 함수는 지정된 호출에 대해 지정된 인밴드 톤을 생성합니다. dwToneMode에 대해 0으로 이 함수를 호출하면 지정된 호출에서 현재 진행 중인 톤 생성이 중단됩니다. 톤 생성이 진행 중인 동안 lineGenerateTone 또는 lineGenerateDigits 를 호출하면 현재 톤 생성 또는 숫자 생성이 중단되고 새로 지정된 톤 또는 숫자의 생성이 시작됩니다.

구문

LONG lineGenerateTone(
  HCALL                    hCall,
  DWORD                    dwToneMode,
  DWORD                    dwDuration,
  DWORD                    dwNumTones,
  LPLINEGENERATETONE const lpTones
);

매개 변수

hCall

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

dwToneMode

생성할 톤을 정의합니다. 톤은 표준 또는 사용자 지정일 수 있습니다. 사용자 지정 톤은 임의의 빈도 집합으로 구성됩니다. 소수의 표준 톤이 미리 정의되어 있습니다. 톤 지속 시간은 표준 및 사용자 지정 톤 모두에 대해 dwDuration 으로 지정됩니다. dwToneMode 매개 변수는 하나의 비트 집합만 가질 수 있습니다. 비트가 설정되지 않은 경우(값 0이 전달됨) 톤 생성이 취소됩니다. 이 매개 변수는 LINETONEMODE_ 상수 중 하나를 사용합니다.

dwDuration

톤을 유지해야 하는 기간(밀리초)입니다. dwDuration의 경우 값 0은 지정된 톤에 대한 기본 기간을 사용합니다. 기본값은 다음과 같습니다.

사용자 지정: 일반적으로 사용자 상호 작용 또는 장비 시간 제한에 의해 차단될 때까지 톤이 유지됩니다.

RINGBACK: 일반적으로 사용자 상호 작용 또는 장비 시간 제한에 의해 차단될 때까지 톤이 유지됩니다.

사용 중: 일반적으로 사용자 상호 작용 또는 장비 시간 제한에 의해 종료될 때까지 톤이 유지됩니다.

BEEP: 일반적으로 사용자 상호 작용 또는 장비 시간 제한에 의해 차단될 때까지 톤이 유지됩니다.

청구: 고정(단일 주기).

dwNumTones

lpTones 배열의 항목 수입니다. dwToneMode가 CUSTOM과 같지 않으면 이 매개 변수는 무시됩니다.

lpTones

톤 구성 요소를 지정하는 LINEGENERATETONE 배열에 대한 포인터입니다. 이 매개 변수는 LINETONEMODE_BUSY 같은 표준 LINETONEMODE_ 상수 톤에 대해 무시됩니다. lpTones가 다중 주파수 톤인 경우 다양한 톤이 동시에 재생됩니다.

반환 값

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

LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALTONEMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALTONE, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

설명

lineGenerateTone 함수는 톤 생성이 완료된 시점이 아니라 톤 생성이 성공적으로 시작되었을 때 성공적으로 완료된 것으로 간주됩니다. 함수를 사용하면 링백, 사용 중인 톤 및 비프음과 같은 미리 정의된 여러 톤을 인밴드 생성할 수 있습니다. 또한 구성 요소 주파수, 주기 및 볼륨을 지정하여 사용자 지정 톤을 제작할 수 있습니다. 이러한 톤은 인밴드 톤으로 생성되기 때문에 일반적으로 톤 생성이 효과적이려면 호출이 연결된 상태여야 합니다. 톤 생성이 완료되거나 톤 생성이 취소되면 LINE_GENERATE 메시지가 애플리케이션으로 전송됩니다.

호출 소유자인 모든 애플리케이션에서 호출당 하나의 인밴드 생성 요청(톤 생성 또는 숫자 생성)만 진행되도록 허용됩니다. 이는 현재 통화에서 톤 생성이 진행 중인 경우 lineGenerateDigits 를 호출하면 톤 생성이 취소됨을 의미합니다.

LINEERR_INVALPOINTER 오류 값이 반환되면 지정된 lpTones 매개 변수가 잘못되었거나 dwNumTones 매개 변수로 지정된 값이 너무 큽니다.