lineOpen 함수(tapi.h)

아티클
03/08/2023

lineOpen 함수는 디바이스 식별자가 지정한 선 디바이스를 열고 열린 해당 줄 디바이스에 대한 줄 핸들을 반환합니다. 이 줄 핸들은 라인 디바이스의 후속 작업에 사용됩니다.

구문

LONG lineOpen(
  HLINEAPP               hLineApp,
  DWORD                  dwDeviceID,
  LPHLINE                lphLine,
  DWORD                  dwAPIVersion,
  DWORD                  dwExtVersion,
  DWORD_PTR              dwCallbackInstance,
  DWORD                  dwPrivileges,
  DWORD                  dwMediaModes,
  LPLINECALLPARAMS const lpCallParams
);

매개 변수

hLineApp

TAPI를 사용하여 애플리케이션 등록을 처리합니다.

dwDeviceID

열 줄 디바이스를 식별합니다. 유효한 디바이스 식별자 또는 값일 수 있습니다.

값	의미
LINEMAPPER	이 값은 lpCallParams에 지정된 속성을 지원하는 시스템에서 선 디바이스를 여는 데 사용됩니다. 애플리케이션은 lineGetID 를 사용하여 열린 라인 디바이스의 식별자를 확인할 수 있습니다.

lphLine

열린 줄 디바이스를 나타내는 핸들과 함께 로드되는 HLINE 핸들에 대한 포인터입니다. 열린 줄 디바이스에서 다른 함수를 호출할 때 이 핸들을 사용하여 디바이스를 식별합니다.

dwAPIVersion

애플리케이션 및 전화 통신 API가 작동하기로 합의한 API 버전 번호입니다. 이 숫자는 lineNegotiateAPIVersion을 사용하여 가져옵니다.

dwExtVersion

애플리케이션 및 서비스 공급자가 작동에 동의하는 확장 버전 번호입니다. 애플리케이션에서 확장을 사용하지 않는 경우 이 숫자는 0입니다. 이 숫자는 lineNegotiateExtVersion을 사용하여 가져옵니다.

dwCallbackInstance

사용자 instance 데이터는 이 줄에 연결된 각 메시지 또는 이 줄의 주소 또는 호출과 함께 애플리케이션에 다시 전달됩니다. 이 매개 변수는 전화 통신 API에서 해석되지 않습니다.

dwPrivileges

호출 알림을 받을 때 애플리케이션이 원하는 권한 이 매개 변수에는 하나 이상의 LINECALLPRIVILEGE_ 상수가 포함됩니다. TAPI 버전 2.0 이상을 사용하는 애플리케이션의 경우 이 매개 변수의 값을 하나 이상의 LINEOPENOPTION_ 상수와 결합할 수도 있습니다.

LINEOPENOPTION_SINGLEADDRESS 옵션을 지정하면 애플리케이션은 lpCallParams 매개 변수가 가리키는 LINECALLPARAMS 구조체의 dwAddressID 멤버가 지정한 주소에 표시되는 새 호출에만 관심이 있습니다(지정해야 합니다).

LINEOPENOPTION_SINGLEADDRESS 지정되었지만 lpCallParams 가 잘못되었거나 포함된 dwAddressID 가 줄에 없으면 열기가 실패하고 LINERR_INVALADDRESSID.

LINECALLPARAMS 구조체의 dwAddressID 멤버를 원하는 주소로 설정하는 것 외에도 애플리케이션은 LINECALLPARAMS의 dwAddressMode를 LINEADDRESSMODE_ADDRESSID 설정해야 합니다.

LINEOPENOPTION_SINGLEADDRESS 옵션은 LINE_NEWCALL 메시지를 사용하여 서비스 공급자가 만든 호출의 TAPI의 초기 호출 소유권 할당에만 영향을 줍니다. LINECALLPRIVILEGE_MONITOR 있는 줄을 여는 애플리케이션은 줄에서 생성된 모든 호출에 대한 모니터링 핸들을 계속 수신합니다. 또한 애플리케이션은 호출을 수행하거나 열린 줄의 다른 주소에 영향을 주는 다른 작업을 수행하는 방식으로 제한되지 않습니다.

LINEOPENOPTION_PROXY 옵션을 지정하면(TAPI 2.0 이상만 해당) 애플리케이션은 처리할 준비가 된 특정 프록시 요청도 표시해야 합니다. 이렇게 하려면 lpCallParams 매개 변수에서 dwDevSpecificSize 및 dwDevSpecificOffset 멤버가 DWORD의 배열을 구분하도록 설정된 LINECALLPARAMS 구조체에 대한 포인터를 전달합니다. 이 배열의 각 요소는 LINEPROXYREQUEST_ 상수 중 하나를 포함해야 합니다. 예를 들어 에이전트 관련 함수 5개를 모두 지원하는 프록시 처리기 애플리케이션은 정의된 5개의 LINEPROXYREQUEST_ 값을 포함하는 5개의 DWORD(dwDevSpecificSize 는 20진수)의 배열을 전달합니다.

프록시 요청 처리기 애플리케이션은 라인 디바이스를 제어할 수 있는 권한이 있는 모든 컴퓨터에서 실행할 수 있습니다. 그러나 요청은 서비스 공급자가 실제로 라인 디바이스를 제어하는 실행 중인 서버를 통해 항상 라우팅됩니다. 따라서 프록시 요청(예: ACD 에이전트 제어)을 처리하는 애플리케이션이 서비스 공급자와 함께 서버에서 직접 실행되는 경우 가장 효율적입니다.

동일한 애플리케이션 또는 다른 애플리케이션에서 라인 디바이스를 열고 이미 등록된 애플리케이션과 동일한 프록시 요청을 처리하기 위해 등록하려는 후속 시도는 LINEERR_NOTREGISTERED 실패합니다.

줄에서 요청 처리를 중지하기 위해 애플리케이션은 lineClose를 호출하기만 하면 됩니다.

다른 플래그 조합은 LINEERR_INVALPRIVSELECT 오류를 반환합니다.

dwMediaModes

애플리케이션에 대한 미디어 유형 또는 관심 모드입니다. 이 매개 변수는 애플리케이션을 지정된 미디어 형식에 대한 수신 호출 및 호출 핸드오프의 잠재적 대상으로 등록하는 데 사용됩니다. 이 매개 변수는 dwPrivileges 의 비트 LINECALLPRIVILEGE_OWNER 설정된 경우에만 의미가 있습니다(그렇지 않으면 무시됨). 이 매개 변수는 하나 이상의 LINEMEDIAMODE_ 상수를 사용합니다.

lpCallParams

LINECALLPARAMS 형식의 구조체에 대한 포인터입니다. 이 포인터는 LINEMAPPER 또는 LINEOPENOPTION_PROXY 사용되는 경우에만 사용됩니다. 그렇지 않으면 lpCallParams 가 무시됩니다. 회선 디바이스에서 제공할 수 있어야 하는 호출 매개 변수에 대해 설명합니다.

반환 값

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

LINEERR_ALLOCATED, LINEERR_LINEMAPPERFAILED, LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_INVALPRIVSELECT, LINEERR_REINIT, LINEERR_NODEVICE, LINEERR_OPERATIONUNAVAIL.

설명

LINEERR_ALLOCATED 반환되는 경우 다른 프로세스에서 독점적으로 열리는 직렬 포트와 같은 "영구적" 조건으로 인해 줄을 열 수 없습니다. LINEERR_RESOURCEUNAVAIL 반환되는 경우 DSP 프로세서 주기 또는 메모리와 같은 동적 리소스 초과 커밋으로 인해 줄을 열 수 없습니다. 이러한 초과 커밋은 미디어 유형 또는 톤 모니터링으로 인해 일시적일 수 있으며, 다른 애플리케이션의 이러한 활동 변경으로 인해 짧은 기간 내에 줄을 다시 열 수 있습니다. LINEERR_REINIT 반환되고 TAPI 다시 초기화가 요청된 경우(예: 전화 통신 서비스 공급자를 추가하거나 제거한 결과) lineOpen 요청은 마지막 애플리케이션이 API 사용을 종료할 때까지( lineShutdown 사용) 이 오류로 거부됩니다. 이때 새 구성이 유효해지고 애플리케이션이 다시 한 번 lineInitializeEx를 호출할 수 있습니다.

줄을 열면 항상 애플리케이션이 줄에서 사용할 수 있는 주소에 대해 호출할 수 있습니다. 수신 호출을 처리하거나 줄에서 호출 핸드오프의 대상이 되는 애플리케이션의 기능은 dwMediaModes 매개 변수에 의해 결정됩니다. lineOpen 함수는 호출을 모니터링하거나 지정된 미디어 형식의 호출 소유권을 받는 데 관심이 있는 것으로 애플리케이션을 등록합니다. 애플리케이션이 호출을 모니터링하려는 경우 LINECALLPRIVILEGE_MONITOR 지정할 수 있습니다. 애플리케이션에서 발신 호출만 하려는 경우 LINECALLPRIVILEGE_NONE 지정할 수 있습니다. 애플리케이션이 분류되지 않은 호출(알 수 없는 미디어 유형의 호출)을 제어하려는 경우 LINECALLPRIVILEGE_OWNER 및 LINEMEDIAMODE_UNKNOWN 지정할 수 있습니다. 그렇지 않으면 애플리케이션은 처리에 관심이 있는 미디어 형식을 지정해야 합니다. 애플리케이션은 lineSetCallPrivilege 함수를 호출하여 LINECALLPRIVILEGES_Constants 지정된 호출 권한을 변경할 수 있습니다.

lineOpen으로 지정된 미디어 형식은 초기 수신 호출 유형 결정에 대한 공급자의 미디어 형식 모니터링에 대한 기본값에 를 추가합니다. lineMonitorMedia 함수는 LINE_MONITORMEDIA 메시지를 제어하는 마스크를 수정합니다. 소유자 권한으로 라인 디바이스가 열리고 확장 미디어 유형이 등록되지 않은 경우 오류 LINEERR_INVALMEDIAMODE 반환됩니다.

회선 디바이스를 성공적으로 연 애플리케이션은 항상 lineMakeCall, lineUnpark, linePickup 및 lineSetupConference ( NULLhCall 포함)를 사용하여 호출을 시작할 수 있으며 lineForward 를 사용할 수 있습니다(디바이스 기능, 선 상태 등에서 허용한다고 가정).

단일 애플리케이션은 여러 미디어 형식을 처리하기 위해 동시에 여러 플래그를 지정할 수 있습니다. 여러 애플리케이션이 동일한 미디어 유형에 대해 동일한 라인 디바이스를 열면 충돌이 발생할 수 있습니다. 이러한 충돌은 사용자가 애플리케이션에 상대적 우선 순위를 할당하는 우선 순위 체계에 의해 해결됩니다. 사용자는 lineSetAppPriority 함수를 호출하여 애플리케이션 우선 순위를 설정할 수 있습니다. 지정된 미디어 유형에 대한 우선 순위가 가장 높은 애플리케이션만 해당 미디어 유형의 호출에 대한 소유권(원치 않는)을 받게 됩니다. 들어오는 전화가 처음 도착하거나 통화가 전달될 때 소유권을 받을 수 있습니다. lineHandoff 함수는 다른 애플리케이션에 대한 호출의 소유권을 전달하기 위해 호출됩니다. 사용자가 애플리케이션에 우선 순위를 할당하지 않고 여러 애플리케이션이 동일한 줄 디바이스를 여는 경우 기본적으로 lineOpen 을 먼저 호출한 애플리케이션의 우선 순위가 가장 높습니다.

모든 애플리케이션(우선 순위가 낮은 애플리케이션 포함) 은 항상 lineGetNewCalls 또는 lineGetConfRelatedCalls를 사용하여 소유권을 획득할 수 있습니다. 애플리케이션이 줄에 호출이 있는 시간에 모니터링할 줄을 열면 기존 호출에 대한 LINE_CALLSTATE 메시지가 새 모니터링 애플리케이션에 자동으로 생성되지 않습니다. 애플리케이션은 줄의 현재 호출 수를 쿼리하여 호출 수를 확인할 수 있으며, 원하는 경우 lineGetNewCalls 를 호출하여 이러한 호출에 대한 핸들을 가져올 수 있습니다.

자동화된 음성을 처리하는 애플리케이션도 대화형 음성 열기 모드를 선택하고 대화형 음성에 가장 낮은 우선 순위를 할당해야 합니다. 그 이유는 서비스 공급자가 모든 음성 미디어 유형을 대화형 음성으로 보고하기 때문입니다. 알 수 없는 미디어 유형에 대한 애플리케이션에서 미디어 유형 결정을 수행하지 않고 대화형 음성 애플리케이션이 회선 디바이스를 열지 않은 경우 음성 통화는 자동화된 음성 애플리케이션에 연결할 수 없으며 삭제됩니다.

동일한 애플리케이션 또는 동일한 애플리케이션의 다른 인스턴스화는 동일하거나 다른 매개 변수를 사용하여 동일한 줄을 여러 번 열 수 있습니다.

애플리케이션이 라인 디바이스를 열 때 협상된 API 버전을 지정해야 하며, 라인의 확장을 사용하려는 경우 줄의 디바이스별 확장 버전을 지정해야 합니다. 이러한 버전 번호는 lineNegotiateAPIVersion 및 lineNegotiateExtVersion을 사용하여 가져와야 합니다. 버전 번호 매기기를 사용하면 다른 API 버전 및 서비스 공급자 버전과 다른 애플리케이션 버전을 혼합하고 일치할 수 있습니다.

LINEMAPPER를 사용하면 애플리케이션에서 원하는 서비스를 통해 간접적으로 선을 선택할 수 있습니다. LINEMAPPER를 사용하여 선 디바이스를 열 때는 다음과 같습니다. LINECALLPARAMS 데이터 구조의 시작부터 dwAddressMode 까지의 모든 멤버는 관련이 있습니다. dwAddressMode가 LINEADDRESSMODE_ADDRESSID 경우 줄의 모든 주소가 허용됨을 의미합니다. 그렇지 않으면 dwAddressMode가 LINEADDRESSMODE_DIALABLEADDR 특정 원본 주소(전화 번호)를 검색하거나 공급자별 확장인 경우 dwOrigAddressSize/오프셋 및 해당 주소가 참조하는 변수 부분의 부분도 관련이 있습니다. dwAddressMode가 공급자별 확장인 경우 dwDeviceSpecific 고정 크기 멤버에 추가 정보를 포함할 수 있습니다.