phoneInitialize 函式 (tapi.h)

發行項
03/02/2024

phoneInitialize 函式已過時。其會繼續由 Tapi.dll 和 Tapi32.dll 導出，以便使用TAPI 1.3和1.4版的應用程式回溯相容性。

使用 TAPI 2.0 版或更新版本的應用程式必須改用 phoneInitializeEx 。

針對 TAPI 1.4 版和更早版本： phoneInitialize 函式會初始化應用程式的TAPI用法，以便後續在 Telephony API 中使用電話功能。它會註冊應用程式的指定通知機制，並傳回應用程式可用的電話裝置數目。

語法

LONG phoneInitialize(
  LPHPHONEAPP   lphPhoneApp,
  HINSTANCE     hInstance,
  PHONECALLBACK lpfnCallback,
  LPCSTR        lpszAppName,
  LPDWORD       lpdwNumDevs
);

參數

lphPhoneApp

指向已填入 TAPI 之應用程式使用句柄的位置指標。

hInstance

用戶端應用程式或 DLL 的實例句柄。

lpfnCallback

叫用以判斷電話裝置上狀態和事件的回呼函式位址。

lpszAppName

包含可顯示字元之 Null 終止字串的指標。如果此參數為非 NULL，則會包含應用程式提供的應用程式名稱。此名稱是在 PHONESTATUS 結構中提供，以使用者易記的方式指出應用程式是手機裝置的目前擁有者。這項資訊對於記錄和狀態報告用途很有用。如果 lpszAppName 為 NULL，則會改用應用程式的檔名。

lpdwNumDevs

DWORD 的指標。此位置會載入應用程式可用的電話裝置數目。

傳回值

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

PHONEERR_INVALAPPNAME、PHONEERR_INIFILECORRUPT、PHONEERR_INVALPOINTER、PHONEERR_NOMEM、PHONEERR_OPERATIONFAILED、PHONEERR_REINIT、PHONEERR_RESOURCEUNAVAIL、PHONEERR_NODEVICE、PHONEERR_NODRIVER PHONEERR_INVALPARAM

備註

應用程式可以使用從零到 dwNumDevs 減一的手機裝置標識碼來參照個別電話裝置。應用程式不應該假設這些電話裝置能夠超出 Assisted Telephony 子集所指定專案以外的任何專案，而不需要先使用 phoneGetDevCaps 函式查詢其裝置功能。

應用程式不應該叫用 phoneInitialize ，而不需後續開啟電話 (至少監視) 。如果應用程式未監視且未使用任何裝置，它應該呼叫 phoneShutdown ，以便在不需要時釋放 TAPI 配置的記憶體資源，而 TAPI 本身可以在不需要時從記憶體卸除。

執行 phoneShutdown 的另一個原因是，如果使用者變更裝置組態， (新增或移除線路或電話) ，則 TAPI 無法通知在此時開啟線路或電話句柄的應用程式。在重新設定發生之後，導致傳送PHONESTATE_REINIT訊息之後，所有應用程式都無法開啟裝置，直到所有應用程式執行 phoneShutdown 為止。

如果有任何服務提供者無法正確初始化， phoneInitialize 函式會失敗，並傳回服務提供者所指出的錯誤。如果傳回PHONEERR_INVALPARAM錯誤值，則指定的 hInstance 參數無效。