phoneInitializeExA 函式 (tapi.h)

發行項
03/05/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 版本，其會傳入 phoneNegotiateAPIVersion) 的 dwAPIHighVersion 參數。不得使用人工高值;值必須正確設定。 TAPI 會將任何較新的訊息或結構轉譯為應用程式版本所支援的值或格式。成功完成此要求時，此位置會填入 TAPI 支援的最高 API 版本，藉此讓應用程式偵測並適應已在舊版 TAPI 的系統上安裝。

lpPhoneInitializeExParams

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

傳回值

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

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 接著會透過呼叫 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 會使用 PostQueuedCompletionStatus 將它傳送至應用程式到 PHONEINITIALIZEEXPARAMS 中 hCompletionPort 成員中指定的應用程式所指定的完成埠，並標記了 PHONEINITIALIZEEXPARAMS 中 dwCompletionKey 成員中指定的完成密鑰。應用程式先前必須使用 CreateIoCompletionPort 建立完成埠。應用程式會使用 GetQueuedCompletionStatus 擷取事件。從 GetQueuedCompletionStatus 傳回時，應用程式已將指定的 dwCompletionKey 寫入 lpCompletionKey 參數所指向的 DWORD，以及傳回至 lpOverlapped 所指向位置的 PHONEMESSAGE 結構的指標。應用程式處理事件之後，應用程式必須呼叫 LocalFree 以釋放用來包含 PHONEMESSAGE 結構的記憶體。由於應用程式已建立完成埠 (因此允許它供其他用途共用) ，因此應用程式必須關閉它;在呼叫 phoneShutdown 之後，應用程式不得關閉完成埠。

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

如果傳回PHONEERR_REINIT，而且 TAPI 重新初始化已要求 (例如，因為新增或移除電話語音服務提供者) ，則會拒絕 phoneInitializeEx 要求，直到最後一個應用程式使用 phoneShutdown) 關閉 API 的使用 (為止。此時，新的組態會生效，而且再次允許應用程式呼叫 phoneInitializeEx。

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

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

注意

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