lineInitialize 函式 (tapi.h)

發行項
03/08/2023

lineInitialize函式已過時。 Tapi.dll 和 Tapi32.dll 會繼續匯出，以便使用 API 1.3 和 1.4 版的應用程式回溯相容性。

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

針對 TAPI 1.4 版和更早版本：lineInitialize函式會初始化應用程式的使用 Tapi.dll，以供後續使用行抽象概念。函式會註冊應用程式的指定通知機制，並傳回應用程式可用的行裝置數目。線條裝置是提供 TAPI 中行前置函式實作的任何裝置。

語法

LONG lineInitialize(
  LPHLINEAPP   lphLineApp,
  HINSTANCE    hInstance,
  LINECALLBACK lpfnCallback,
  LPCSTR       lpszAppName,
  LPDWORD      lpdwNumDevs
);

參數

lphLineApp

已填入 TAPI 應用程式使用控制碼的位置指標。

hInstance

用戶端應用程式或 DLL 的實例控制碼。

lpfnCallback

叫用以判斷線路裝置、位址或撥號狀態和事件的回呼函式位址。如需詳細資訊，請參閱 lineCallbackFunc。

lpszAppName

僅包含可顯示字元之 Null終止文字字串的指標。如果此參數不是 Null，它會包含應用程式的應用程式提供的名稱。此名稱是在 LINECALLINFO 結構中提供，以使用者易記的方式指出應用程式源自或原本接受或接聽通話。這項資訊對於通話記錄用途很有用。如果 lpszAppName 為 Null，則會改用應用程式的檔案名。

lpdwNumDevs

DWORD大小位置的指標。成功完成此要求時，此位置會填入應用程式可用的行裝置數目。

傳回值

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

LINEERR_INVALAPPNAME、LINEERR_OPERATIONFAILED、LINEERR_INIFILECORRUPT、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALPOINTER、LINEERR_REINIT、LINEERR_NODRIVER、LINEERR_NODEVICE、LINEERR_NOMEM LINEERR_NOMULTIPLEINSTANCE。

備註

如果傳回LINEERR_REINIT並要求 TAPI 重新初始化 (，例如因為新增或移除電話語音服務提供者) 而要求 TAPI 重新初始化，則會拒絕 lineInitialize 要求，直到最後一個應用程式使用 lineShutdown) 關閉其 API 的使用 (為止。此時，新的設定會變成有效，而且再次允許應用程式呼叫 lineInitialize。如果傳回LINEERR_INVALPARAM錯誤值，則指定的 hInstance 參數無效。

應用程式可以使用範圍從零到 dwNumDevs 減一的線路裝置識別碼來參考個別線路裝置。應用程式不應假設這些線路裝置除了 Basic Telephony 子集所指定的專案之外，還能夠使用 lineGetDevCaps 和 lineGetAddressCaps來查詢其裝置功能。

應用程式不應該叫用 lineInitialize ，而不需在後續開啟行 (至少用於監視) 。如果應用程式未監視且未使用任何裝置，它應該呼叫 lineShutdown ，以便在不需要的情況下釋放 Tapi.dll 配置的記憶體資源，而且不需要時，Tapi.dll 本身可以從記憶體卸載。

執行 lineShutdown 的另一個原因是，如果使用者變更裝置設定， (新增或移除線路或電話) ，TAPI 就無法通知應用程式在此時開啟線路或電話控制碼。在重新設定發生之後，導致傳送LINEDEVSTATE_REINIT訊息，除非所有應用程式都執行 lineShutdown，否則無法開啟裝置。如果有任何服務提供者無法正確初始化，此函式會失敗，並傳回服務提供者所指出的錯誤。

在所有 TAPI 平臺上， lineInitialize 相當於使用 LINEINITIALIZEEXOPTION_USEHIDDENWINDOW 選項的 lineInitializeEx 。