다음을 통해 공유


lineInitializeExA 함수(tapi.h)

lineInitializeEx 함수는 줄 추상화의 후속 사용을 위해 애플리케이션의 TAPI 사용을 초기화합니다. 애플리케이션의 지정된 알림 메커니즘을 등록하고 애플리케이션에서 사용할 수 있는 줄 디바이스 수를 반환합니다. 라인 디바이스는 전화 통신 API의 줄 접두사 함수에 대한 구현을 제공하는 모든 디바이스입니다.

통사론

LONG lineInitializeExA(
  LPHLINEAPP               lphLineApp,
  HINSTANCE                hInstance,
  LINECALLBACK             lpfnCallback,
  LPCSTR                   lpszFriendlyAppName,
  LPDWORD                  lpdwNumDevs,
  LPDWORD                  lpdwAPIVersion,
  LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
);

매개 변수

lphLineApp

TAPI에 대한 애플리케이션의 사용 핸들로 채워진 위치에 대한 포인터입니다.

hInstance

클라이언트 애플리케이션 또는 DLL의 인스턴스 핸들입니다. 애플리케이션 또는 DLL은 이 매개 변수에 NULL 전달할 수 있습니다. 이 경우 TAPI는 프로세스의 루트 실행 파일의 모듈 핸들을 사용합니다(호출 핸드오프 대상 및 미디어 모드 우선 순위를 식별하기 위해).

lpfnCallback

애플리케이션이 이벤트 알림의 "숨겨진 창" 메서드를 사용하는 경우 회선 디바이스, 주소 또는 호출의 상태 및 이벤트를 확인하기 위해 호출되는 콜백 함수의 주소입니다(자세한 내용은 lineCallbackFunc참조). 이 매개 변수는 무시되며 애플리케이션이 "이벤트 핸들" 또는 "완료 포트" 이벤트 알림 메커니즘을 사용하도록 선택할 때 NULL 설정해야 합니다.

lpszFriendlyAppName

표시 가능한 문자만 포함하는 null종료된 텍스트 문자열에 대한 포인터입니다. 이 매개 변수가 NULL않으면 애플리케이션에 대한 애플리케이션 제공 이름이 포함됩니다. 이 이름은 LINECALLINFO 구조에 제공되어 사용자에게 친숙한 방식으로 애플리케이션이 시작되었거나 원래 전화를 수락하거나 응답했음을 나타냅니다. 이 정보는 호출 로깅 용도로 유용할 수 있습니다. lpszFriendlyAppName NULL경우 애플리케이션의 모듈 파일 이름이 대신 사용됩니다(getModuleFileName함수에서 반환됨).

lpdwNumDevs

DWORD크기의 위치에 대한 포인터입니다. 이 요청이 성공적으로 완료되면 이 위치는 애플리케이션에서 사용할 수 있는 줄 디바이스 수로 채워집니다.

lpdwAPIVersion

DWORD크기의 위치에 대한 포인터입니다. 애플리케이션은 이 함수를 호출하기 전에 이 DWORD지원하도록 설계된 가장 높은 API 버전으로 초기화해야 합니다(예: lineNegotiateAPIVersiondwAPIHighVersion 매개 변수에 전달되는 것과 동일한 값). 인위적으로 높은 값을 사용하면 안 됩니다. 값을 정확하게 설정해야 합니다. TAPI는 최신 메시지 또는 구조를 애플리케이션 버전에서 지원하는 값 또는 형식으로 변환합니다. 이 요청이 성공적으로 완료되면 이 위치는 TAPI에서 지원하는 가장 높은 API 버전으로 채워지게 되므로 애플리케이션이 다른 버전의 TAPI를 사용하여 시스템에 설치된 것을 감지하고 적응할 수 있습니다.

lpLineInitializeExParams

애플리케이션과 TAPI 간의 연결을 설정하는 데 사용되는 추가 매개 변수를 포함하는 LINEINITIALIZEEXPARAMS 형식의 구조에 대한 포인터입니다(특히 애플리케이션에서 선택한 이벤트 알림 메커니즘 및 연결된 매개 변수).

반환 값

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

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NOMEM, LINEERR_INVALPARAM.

발언

애플리케이션은 TAPI가 전화 통신 이벤트의 애플리케이션에 알립니다. 숨겨진 창, 이벤트 핸들 또는 완료 포트의 세 가지 메커니즘 중 하나를 선택해야 합니다.

LINEINITIALIZEEXPARAMS 구조체의 dwOptions 멤버에 LINEINITIALIZEEXOPTION_USEHIDDENWINDOW 지정하여 숨겨진 창 메커니즘을 선택합니다. 이 메커니즘에서(TAPI 버전 1에서 사용할 수 있는 유일한 메커니즘입니다. x 애플리케이션을TAPI는 lineInitializeEx 또는 lineInitialize(TAPI 버전 1.3 및 1.4 애플리케이션의 경우) 함수 동안 애플리케이션 컨텍스트에서 창을 만들고, 게시되는 모든 메시지가 TAPI 자체의 WNDPROC에서 처리되도록 창을 서브클래싱합니다. TAPI에 애플리케이션에 배달할 메시지가 있는 경우 TAPI는 숨겨진 창에 메시지를 게시합니다. 메시지가 수신되면(애플리케이션이 Windows GetMessage 함수를 호출할 때만 발생할 수 있음) Windows는 프로세스 컨텍스트를 애플리케이션의 컨텍스트로 전환하고 TAPI에서 WNDPROC를 호출합니다. 그런 다음 TAPI는 lineInitializeEx(또는 lineInitialize)에 대한 호출에서 애플리케이션이 매개 변수로 제공한 포인터인 lineCallbackProc호출하여 애플리케이션에 메시지를 전달합니다. 이 메커니즘을 사용하려면 애플리케이션에 메시지 큐(서비스 프로세스에는 바람직하지 않음)가 있어야 하며, 전화 통신 이벤트 처리가 지연되지 않도록 해당 큐를 정기적으로 서비스해야 합니다. 숨겨진 창은 lineShutdown 함수 중에 TAPI에 의해 제거됩니다.

이벤트 핸들 메커니즘은 LINEINITIALIZEEXPARAMS 구조체의 dwOptions 멤버에 LINEINITIALIZEEXOPTION_USEEVENT 지정하여 선택합니다. 이 메커니즘에서 TAPI는 애플리케이션을 대신하여 이벤트 개체를 만들고 LINEINITIALIZEEXPARAMShEvent 멤버의 개체에 대한 핸들을 반환합니다. 애플리케이션은 어떤 방식으로든 이 이벤트를 조작해서는 안 됩니다(예: SetEvent , ResetEvent, CloseHandle등) 또는 정의되지 않은 동작 결과를 호출해서는 안 됩니다. 애플리케이션은 WaitForSingleObject 또는 msgWaitForMultipleObjects같은 함수를 사용하여 이 이벤트를 대기할 수 있습니다. TAPI는 애플리케이션에 대한 전화 통신 이벤트 알림이 보류 중일 때마다 이 이벤트를 알립니다. 애플리케이션은 메시지의 내용을 가져오려면 lineGetMessage 호출해야 합니다. 보류 중인 이벤트가 없는 경우 TAPI에서 이벤트를 다시 설정합니다. 이벤트 핸들이 닫히고 lineShutdown 함수 중에 TAPI에 의해 이벤트 개체가 제거됩니다. 애플리케이션은 생성된 이벤트 핸들을 기다릴 필요가 없습니다. 애플리케이션은 lineGetMessage 호출하도록 대신 선택하고 메시지가 큐에 대기될 때까지 대기하는 것을 차단하도록 할 수 있습니다.

완성 포트 메커니즘은 LINEINITIALIZEEXPARAMS 구조체의 dwOptions 멤버에 LINEINITIALIZEEXOPTION_USECOMPLETION PORT를 지정하여 선택합니다. 이 메커니즘에서는 전화 통신 이벤트를 애플리케이션에 보내야 할 때마다 TAPI는 PostQueuedCompletionStatus 사용하여 애플리케이션이 LINEINITIAL의 hCompletionPort 멤버에 지정한 완료 포트로 보냅니다. LINEINITIALIZEEXPARAMS의 dwCompletionKey 멤버에 지정된 완료 키로 태그가 지정된IZEEXPARAMS. 애플리케이션은 이전에 CreateIoCompletionPort사용하여 완료 포트를 만들었어야 합니다. 애플리케이션은 GetQueuedCompletionStatus사용하여 이벤트를 검색합니다. GetQueuedCompletionStatus반환되면 애플리케이션에는 지정된 dwCompletionKeylpCompletionKey 매개 변수가 가리키는 DWORD 기록되고 LINEMESSAGE 구조체에 대한 포인터가 lpOverlapped가리키는 위치로 반환됩니다. 애플리케이션이 이벤트를 처리한 후에는 LocalFree 호출하여 LINEMESSAGE 구조를 포함하는 데 사용되는 메모리를 해제해야 합니다. 애플리케이션이 완료 포트를 만들었기 때문에(따라서 다른 용도로 공유될 수 있음) 애플리케이션은 이를 닫아야 합니다. 애플리케이션은 lineShutdown호출할 때까지 완료 포트를 닫아서는 안됩니다.

다중 스레드 애플리케이션이 이벤트 핸들 메커니즘을 사용하고 있고 둘 이상의 스레드가 핸들 또는 완료 포트 알림 메커니즘에서 대기 중이고 둘 이상의 스레드가 포트에서 대기하는 경우 전화 통신 이벤트가 순서대로 처리될 수 있습니다. 이는 TAPI에서 이벤트 전달 시퀀스 때문이 아니라 스레드의 시간 조각화 또는 별도의 프로세서에서 스레드 실행으로 인해 발생합니다.

LINEERR_REINIT 반환되고 TAPI 다시 초기화가 요청된 경우 예를 들어 전화 통신 서비스 공급자를 추가하거나 제거한 결과, 마지막 애플리케이션이 API 사용을 종료할 때까지(lineShutdown사용) lineInitializeEx 요청이 거부되는 lineInitializeEx. 이때 새 구성이 유효해지고 애플리케이션이 다시 lineInitializeEx호출할 수 있습니다.

LINEERR_INVALPARAM 오류 값이 반환되면 지정된 hInstance 매개 변수가 잘못되었습니다.

애플리케이션은 0에서 dwNumDevs 1까지의 줄 디바이스 식별자를 사용하여 개별 라인 디바이스를 참조할 수 있습니다. 애플리케이션에서는 lineGetDevCaps 및 lineGetAddressCaps먼저 디바이스 기능을 쿼리하지 않고 이러한 줄 디바이스가 특정 TAPI 기능을 사용할 수 있다고 가정해서는 안 됩니다.

메모

tapi.h 헤더는 UNICODE 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 lineInitializeEx를 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입대한 규칙을 참조하세요.

요구 사항

요구
대상 플랫폼 Windows
헤더 tapi.h
라이브러리 Tapi32.lib
DLL Tapi32.dll

참고 항목

기본 전화 통신 서비스 참조

LINECALLINFO

LINEINITIALIZEEXPARAMS

LINEMESSAGE

TAPI 2.2 참조 개요

lineCallbackFunc

lineGetAddressCaps

lineGetDevCaps

lineGetMessage

lineInitialize

lineNegotiateAPIVersion

lineShutdown