phoneInitializeExA 함수(tapi.h)

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

통사론

LONG phoneInitializeExA(
  LPHPHONEAPP               lphPhoneApp,
  HINSTANCE                 hInstance,
  PHONECALLBACK             lpfnCallback,
  LPCSTR                    lpszFriendlyAppName,
  LPDWORD                   lpdwNumDevs,
  LPDWORD                   lpdwAPIVersion,
  LPPHONEINITIALIZEEXPARAMS lpPhoneInitializeExParams
);

매개 변수

lphPhoneApp

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

hInstance

클라이언트 애플리케이션 또는 DLL의 인스턴스 핸들입니다. 애플리케이션 또는 DLL은 이 매개 변수에 대해 NULL 전달할 수 있습니다. 이 경우 TAPI는 프로세스의 루트 실행 파일의 모듈 핸들을 사용합니다.

lpfnCallback

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

lpszFriendlyAppName

표시 가능한 문자만 포함하는 null종료된 문자열에 대한 포인터입니다. 이 매개 변수가 NULL않으면 애플리케이션에 대한 애플리케이션 제공 이름이 포함됩니다. 이 이름은 PHONESTATUS 구조에 제공되어 사용자에게 친숙한 방식으로 휴대폰 디바이스의 소유권이 있는 애플리케이션을 나타냅니다. lpszFriendlyAppName NULL경우 애플리케이션의 모듈 파일 이름이 대신 사용됩니다(getModuleFileName함수에서 반환한 ).

lpdwNumDevs

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

lpdwAPIVersion

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

lpPhoneInitializeExParams

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

반환 값

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

PHONEERR_INVALAPPNAME, PHONEERR_OPERATIONFAILED, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_REINIT, PHONEERR_NOMEM, PHONEERR_INVALPARAM.

발언

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

• 숨김 창 메커니즘은 PHONEINITIALIZEEXPARAMS 구조의 dwOptions 멤버에 PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW 지정하여 선택합니다. TAPI 버전 1에서 사용할 수 있는 유일한 메커니즘인 이 메커니즘에서 TAPI는 phoneInitializeEx 함수 중에 애플리케이션 컨텍스트에서 창을 만들고, 게시된 모든 메시지가 TAPI 자체의 WNDPROC에서 처리되도록 창을 서브클래싱합니다. TAPI에 애플리케이션에 배달할 메시지가 있는 경우 TAPI는 숨겨진 창에 메시지를 게시합니다. 메시지가 수신되면(애플리케이션이 Windows GetMessage 함수를 호출할 때만 발생할 수 있음) Windows는 프로세스 컨텍스트를 애플리케이션의 컨텍스트로 전환하고 TAPI에서 WNDPROC를 호출합니다. TAPI는 phoneInitializeEx 호출에서 애플리케이션이 매개 변수로 제공한 포인터인 phoneCallbackFunc호출하여 애플리케이션에 메시지를 전달합니다(또는 TAPI 버전 1.3 및 1.4 애플리케이션의 경우 phoneInitialize). 이 메커니즘을 사용하려면 애플리케이션에 메시지 큐(서비스 프로세스에는 바람직하지 않음)가 있어야 하며, 전화 통신 이벤트 처리가 지연되지 않도록 해당 큐를 정기적으로 서비스해야 합니다. 숨겨진 창은 phoneShutdown 함수 중에 TAPI에 의해 제거됩니다.
• 이벤트 핸들 메커니즘은 PHONEINITIALIZEEXPARAMS 구조의 dwOptions 멤버에 PHONEINITIALIZEEXOPTION_USEEVENT 지정하여 선택합니다. 이 메커니즘에서 TAPI는 애플리케이션을 대신하여 이벤트 개체를 만들고 PHONEINITIALIZEEXPARAMShEvent 멤버의 개체에 대한 핸들을 반환합니다. 애플리케이션은 어떤 방식으로든 이 이벤트를 조작해서는 안 됩니다(예: SetEvent , ResetEvent, CloseHandle등) 또는 정의되지 않은 동작 결과를 호출해서는 안 됩니다. 애플리케이션은 WaitForSingleObject 또는 msgWaitForMultipleObjects같은 함수를 사용하여 이 이벤트를 대기할 수 있습니다. TAPI는 애플리케이션에 대한 전화 통신 이벤트 알림이 보류 중일 때마다 이 이벤트를 알립니다. 애플리케이션은 phoneGetMessage 호출하여 메시지 내용을 가져와야 합니다. 보류 중인 이벤트가 없는 경우 TAPI에서 이벤트를 다시 설정합니다. 이벤트 핸들이 닫히고 phoneShutdown 함수 중에 TAPI에 의해 이벤트 개체가 제거됩니다. 애플리케이션은 생성된 이벤트 핸들을 기다릴 필요가 없습니다. 애플리케이션은 대신 phoneGetMessage 호출하도록 선택하고 메시지가 큐에 대기될 때까지 대기하는 것을 차단하도록 할 수 있습니다.
• 완료 포트 메커니즘은 PHONEINITIALIZEEXPARAMS 구조의 dwOptions 멤버에 PHONEINITIALIZEEXOPTION_USECOMPLETION PORT를 지정하여 선택합니다. 이 메커니즘에서는 전화 통신 이벤트를 애플리케이션에 보내야 할 때마다 TAPI는 PostQueuedCompletionStatus 사용하여 애플리케이션을 PHONEINITIAL의 hCompletionPort 멤버에 지정한 완료 포트로 보냅니다.IZEEXPARAMS- PHONEINITIALIZEEXPARAMS의 dwCompletionKey 멤버에 지정된 완료 키로 태그가 지정되어. 애플리케이션은 이전에 CreateIoCompletionPort사용하여 완료 포트를 만들었어야 합니다. 애플리케이션은 GetQueuedCompletionStatus사용하여 이벤트를 검색합니다. GetQueuedCompletionStatus반환되면 애플리케이션에는 지정된 dwCompletionKey lpCompletionKey 매개 변수가 가리키는 DWORD 기록됩니다. 및 PHONEMESSAGE 구조체에 대한 포인터가 lpOverlapped가리키는 위치로 반환됩니다. 애플리케이션이 이벤트를 처리한 후 애플리케이션은 LocalFree 호출하여 PHONEMESSAGE 구조를 포함하는 데 사용되는 메모리를 해제해야 합니다. 애플리케이션이 완료 포트를 만들었기 때문에(따라서 다른 용도로 공유될 수 있음) 애플리케이션은 이를 닫아야 합니다. 애플리케이션은 phoneShutdown호출할 때까지 완료 포트를 닫아서는 안됩니다.

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

PHONEERR_REINIT 반환되고 TAPI 다시 초기화가 요청된 경우(예: 전화 통신 서비스 공급자를 추가하거나 제거한 결과) phoneInitializeEx 요청은 마지막 애플리케이션이 API 사용을 종료할 때까지(phoneShutdown사용) 이 오류로 거부됩니다. 이때 새 구성이 적용되고 애플리케이션이 다시 한 번 phoneInitializeEx호출할 수 있습니다.

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

애플리케이션은 0에서 dwNumDevs 1까지의 전화 장치 식별자를 사용하여 개별 전화 디바이스를 참조할 수 있습니다. 애플리케이션에서는 먼저 phoneGetDevCaps디바이스 기능을 쿼리하지 않고도 이러한 휴대폰 디바이스가 특정 TAPI 기능을 사용할 수 있다고 가정해서는 안 됩니다.

메모

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

요구 사항

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

참고 항목

PHONEINITIALIZEEXPARAMS

PHONEMESSAGE

PHONESTATUS

추가 전화 서비스 함수

TAPI 2.2 참조 개요

phoneCallbackFunc

phoneGetDevCaps

phoneGetMessage

phoneNegotiateAPIVersion

phoneShutdown