phoneInitializeExA 함수(tapi.h)

아티클
08/26/2023

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

lpPhoneInitializeExParams

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

반환 값

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

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

설명

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

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

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

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

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

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

참고

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