lineHandoff 함수(tapi.h)

아티클
08/26/2023

lineHandoff 함수는 다른 애플리케이션에 대해 지정된 호출의 소유권을 부여합니다. 애플리케이션은 파일 이름으로 직접 지정하거나 지정된 미디어 모드의 호출을 처리하는 우선 순위가 가장 높은 애플리케이션으로 간접적으로 지정할 수 있습니다.

구문

LONG lineHandoff(
  HCALL  hCall,
  LPCSTR lpszFileName,
  DWORD  dwMediaMode
);

매개 변수

hCall

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

lpszFileName

null로 끝나는 문자열에 대한 포인터입니다. 이 포인터 매개 변수가 NULL이 아닌 경우 핸드오프의 대상인 애플리케이션의 파일 이름이 포함됩니다. NULL인 경우 핸드오프 대상은 지정된 미디어 모드에 대한 소유자 권한에 대한 줄을 연 가장 높은 우선 순위 애플리케이션입니다. 유효한 파일 이름에는 파일의 경로가 포함되지 않습니다.

dwMediaMode

간접 핸드오프 대상을 식별하는 데 사용되는 미디어 모드입니다. dwMediaMode 매개 변수는 호출의 소유권을 받을 대상 애플리케이션을 간접적으로 식별합니다. lpszFileName이 NULL이 아닌 경우 이 매개 변수는 무시됩니다. 이 매개 변수는 LINEMEDIAMODE_ 상수 중 하나만 사용합니다.

반환 값

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

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_TARGETNOTFOUND, LINEERR_INVALPOINTER, LINEERR_TARGETSELF, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NOTOWNER.

설명

lineHandoff 함수는 호출하는 애플리케이션이 간접 핸드오프(즉, lpszFileName 매개 변수를 NULL로 설정)를 시도하면 LINEERR_TARGETSELF 반환하고 TAPI는 애플리케이션 자체가 지정된 미디어 모드의 우선 순위가 가장 높은 애플리케이션임을 확인합니다. LINEERR_TARGETNOTFOUND 반환되면 호출 핸드오프 대상을 찾을 수 없습니다. 명명된 애플리케이션이 lineOpen의 dwPrivileges 매개 변수에서 LINECALLPRIVILEGE_OWNER 비트와 동일한 줄을 열지 않은 경우에 발생할 수 있습니다. 또는 미디어 모드 핸드오프의 경우 lineOpen의 dwPrivileges 매개 변수 및 lineOpen의 dwMediaModes 매개 변수에 지정된 미디어 모드의 LINECALLPRIVILEGE_OWNER 비트와 동일한 줄을 연 애플리케이션이 없습니다.

호출 핸드오프를 사용하면 호출의 소유권을 애플리케이션 간에 전달할 수 있습니다. 핸드오프에는 두 가지 유형이 있습니다. 첫 번째 형식에서 애플리케이션이 대상 애플리케이션의 파일 이름을 알고 있는 경우 해당 파일 이름을 지정할 수 있습니다. 대상 애플리케이션의 instance 라인 디바이스를 열면 호출의 소유권이 다른 애플리케이션에 전달되고, 그렇지 않으면 핸드오프가 실패하고 오류가 반환됩니다. 이 핸드오프 형식은 호출 핸들이 핸드오프를 요청하는 애플리케이션과 동일한 파일 이름으로 전달되는 경우 성공합니다.

두 번째 핸드오프 유형은 미디어 모드를 기반으로 합니다. 이 경우 애플리케이션은 미디어 모드를 통해 대상 애플리케이션을 간접적으로 지정합니다. 현재 해당 미디어 모드에 대한 라인 디바이스를 연 가장 높은 우선 순위 애플리케이션이 핸드오프의 대상입니다. 이러한 애플리케이션이 없으면 핸드오프가 실패하고 오류가 반환됩니다.

lineHandoff 함수는 호출의 미디어 모드를 변경하지 않습니다. 호출의 미디어 모드를 변경하려면 애플리케이션에서 호출 시 lineSetMediaMode 를 사용하여 새 미디어 모드를 지정해야 합니다. 이렇게 하면 호출의 LINECALLINFO 구조에 저장된 대로 호출의 미디어 모드가 변경됩니다.

핸드오프가 성공하면 수신 애플리케이션은 호출에 대한 LINE_CALLSTATE 메시지를 받습니다. 이 메시지는 수신 애플리케이션에 호출에 대한 소유자 권한이 있음을 나타냅니다(dwParam3). 또한 통화에 대한 소유자 및/또는 모니터 수가 변경되었을 수 있습니다. 이는 LINE_CALLINFO 메시지에 의해 보고되며 수신 애플리케이션은 lineGetCallStatus 및 lineGetCallInfo 를 호출하여 수신된 호출에 대한 자세한 정보를 검색할 수 있습니다.

수신 애플리케이션은 먼저 LINECALLINFO에서 미디어 모드를 검사 합니다. 단일 미디어 모드 플래그만 설정된 경우 호출은 공식적으로 해당 미디어 모드이며 애플리케이션이 그에 따라 작동할 수 있습니다. UNKNOWN 및 기타 미디어 모드 플래그가 설정된 경우 호출의 미디어 모드는 공식적으로 UNKNOWN이지만 LINECALLINFO에서 플래그가 설정된 미디어 모드 중 하나로 간주됩니다. 애플리케이션은 우선 순위가 가장 높은 미디어 모드를 검색해야 한다고 가정해야 합니다.

프로브가 성공하면(해당 미디어 모드 또는 다른 미디어 모드의 경우) 애플리케이션은 LINECALLINFO 의 미디어 모드 멤버를 인식된 단일 미디어 모드로 설정해야 합니다. 미디어 모드 플래그가 LINECALLINFO 미디어 모드와 일치하는 경우 애플리케이션이 그에 따라 작동할 수 있습니다. 다른 미디어 모드를 결정하는 경우 먼저 해당 미디어 모드에 대한 호출을 해제해야 합니다.

프로브가 실패하면 애플리케이션은 LINECALLINFO 에서 해당 미디어 모드 플래그를 지우고 dwMediaMode 를 LINEMEDIAMODE_UNKNOWN 지정하여 호출을 전달해야 합니다. 또한 호출 핸들의 할당을 취소해야 합니다(또는 모니터링으로 다시 되돌리기).

미디어 모드 중 어느 것도 결정을 내리는 데 성공하지 못한 경우 미디어 애플리케이션이 UNKNOWN에 대한 호출을 전달하려고 할 때 LINECALLINFO 의 미디어 모드 필드에 UNKNOWN 플래그만 설정된 상태로 유지됩니다. 애플리케이션이 호출의 유일한 나머지 소유자인 경우 최종 lineHandoff 가 실패합니다. 이렇게 하면 호출을 삭제하고 핸들의 할당을 취소해야 하며, 이 경우 호출이 중단됨을 애플리케이션에 알립니다. 호출에 대한 애플리케이션 호출 권한은 이 작업에서 변경되지 않지만 애플리케이션은 lineSetCallPrivilege를 사용하여 해당 권한을 호출로 변경할 수 있습니다.