phoneInitializeExA 函式（tapi.h）

發行項
11/20/2024

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 版本（例如，它會傳入 dwAPIHighVersion 參數 phoneNegotiateAPIVersion的相同值）。不得使用人工高值;值必須正確設定。 TAPI 會將任何較新的訊息或結構轉譯為應用程式版本所支援的值或格式。成功完成此要求后，此位置會填入 TAPI 所支援的最高 API 版本，讓應用程式偵測並適應已安裝於舊版 TAPI 的系統上。

lpPhoneInitializeExParams

PHONEINITIALIZEEXPARAMS 類型的結構指標包含用來建立應用程式與 TAPI 關聯的其他參數（特別是應用程式選取的事件通知機制和相關聯的參數）。

傳回值

如果要求成功或發生錯誤，則傳回零。可能的傳回值為：

PHONEERR_INVALAPPNAME、PHONEERR_OPERATIONFAILED、PHONEERR_INIFILECORRUPT、PHONEERR_INVALPOINTER、PHONEERR_REINIT、PHONEERR_NOMEM、PHONEERR_INVALPARAM。

言論

應用程式必須選取三種機制之一，TAPI 會通知電話語音事件的應用程式：隱藏視窗、事件句柄或完成埠。

在 PHONEINITIALIZEEXPARAMS 結構中 PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW指定 dwOptions 成員，即可選取 隱藏視窗 機制。在此機制中（這是 TAPI 第 1 版唯一可用的機制。x 應用程式），TAPI 會在 phoneInitializeEx 函式期間，在應用程式內容中建立視窗，並子類別化視窗，讓張貼到它的所有訊息都由 TAPI 本身的 WNDPROC 處理。當 TAPI 有訊息要傳遞至應用程式時，TAPI 會將訊息張貼至隱藏的視窗。收到訊息時（只有在應用程式呼叫 Windows GetMessage 函式時，Windows 才會將進程內容切換至應用程式的內容，並在 TAPI 中叫用 WNDPROC。 TAPI 接著會呼叫 phoneCallbackFunc將訊息傳遞至應用程式，這是應用程式在其呼叫 phoneInitializeEx 時提供做為參數的指標（或 phoneInitialize，適用於 TAPI 1.3 版和 1.4 應用程式）。此機制要求應用程式要有消息佇列（這不適合服務進程），並定期服務該佇列，以避免延遲處理電話語音事件。隱藏視窗會在 phoneShutdown 函式期間被 TAPI 終結。
在 PHONEINITIALIZEEXPARAMS 結構中，指定 dwOptions 成員中的 事件句柄 機制，以選取PHONEINITIALIZEEXOPTION_USEEVENT。在此機制中，TAPI 會代表應用程式建立事件物件，並將句柄傳回 PHONEINITIALIZEEXPARAMS中 hEvent 成員中的物件。應用程式不得以任何方式操作此事件（例如，不得呼叫 setEvent、ResetEvent、CloseHandle等等）或未定義的行為結果：應用程式只能使用 WaitForSingleObject 或 MsgWaitForMultipleObjects等函式等候此事件。 TAPI 會在應用程式擱置電話語音事件通知時發出此事件訊號;應用程式必須呼叫 phoneGetMessage，才能擷取訊息的內容。當沒有任何事件擱置時，TAPI 會重設事件。事件句柄已關閉，而TAPI在 phoneShutdown 函式期間終結的事件物件。應用程式不需要等候所建立的事件句柄;應用程式可以選擇改為呼叫 phoneGetMessage，並讓它封鎖等候訊息排入佇列。
選取 完成埠 機制，方法是在 PHONEINITIALIZEEXPARAMS 結構中指定 dwOptions 成員中的 PHONEINITIALIZEEXOPTION_USECOMPLETION PORT。在此機制中，每當需要傳送電話語音事件給應用程式時， TAPI 會使用 postQueuedCompletionStat us PostQueuedCompletionStatus 將它傳送至應用程式到 hCompletionPort 成員中指定的完成埠，PHONEINITIALIZEEXPARAMS中，以 dwCompletionKey 成員標記。應用程式先前必須使用 createIoCompletionPort 建立完成埠。應用程式會使用 getQueuedCompletionStatus 擷取事件。從 getQueuedCompletionStatus傳回時，應用程式具有指定的 dwCompletionKey 寫入 DWORD 由 lpCompletionKey 參數所指向的 DWORD，和 PHONEMESSAGE 結構的指標會傳回 lpOverlapped所指向的位置。在應用程式處理事件之後，應用程式必須呼叫 LocalFree，以釋放用來包含 PHONEMESSAGE 結構的記憶體。因為應用程式已建立完成埠（因此允許它供其他用途共用），所以應用程式必須關閉它;應用程式必須等到呼叫 phoneShutdown之後，才能關閉完成埠。

當多線程應用程式使用事件句柄機制，且多個線程正在等候句柄時，或完成埠通知機制和一個以上的線程正在等候埠時，電話語音事件可能會依順序處理。這不是因為從 TAPI 傳遞事件的順序，而是因為線程的時間切割或在個別處理器上執行線程所造成。

如果傳回PHONEERR_REINIT並已要求TAPI重新初始化（例如，新增或移除電話語音服務提供者的結果），則 PhoneInitializeEx 要求遭到拒絕，直到最後一個應用程式關閉其API使用量為止（使用 phoneShutdown）。屆時，新的組態會變得有效，而且再次允許應用程式呼叫 phoneInitializeEx。

如果傳回PHONEERR_INVALPARAM錯誤值，指定的 hInstance 參數無效。

應用程式可以使用從零到 dwNumDevs 減一的電話裝置標識碼來參考個別電話裝置。應用程式不應該假設這些電話裝置能夠執行任何特定的 TAPI 功能，而不需要先透過 phoneGetDevCaps來查詢其裝置功能。

注意

tapi.h 標頭會根據 UNICODE 預處理器常數的定義，將 phoneInitializeEx 定義為自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。