TSPI_providerRemove函式 (tspi.h)

發行項
03/13/2024

TSPI_providerRemove函式已過時。 TAPI 1.4 版或更早版本的服務提供者可以實作此 TSPI 函式。 TAPI 2.0 版或更新版本的 TSP 會實作 TUISPI_providerRemove。

TSPI_providerRemove函式會要求使用者確認刪除服務提供者。服務提供者負責移除服務提供者在 addProvider 時間新增的任何登錄專案，以及不再需要的任何其他模組和檔案。

語法

LONG TSPIAPI TSPI_providerRemove(
  HWND  hwndOwner,
  DWORD dwPermanentProviderID
);

參數

hwndOwner

函式可在移除期間建立任何所需的對話框視窗的父視窗句柄。

dwPermanentProviderID

服務提供者的永久提供者標識碼。

傳回值

如果函式成功或發生錯誤，則傳回零。可能的傳回值如下所示：

LINEERR_OPERATIONFAILED、LINEERR_INIFILECORRUPT、LINEERR_NOMEM、LINEERR_INVALPARAM。

備註

如果服務提供者傳回成功，此函式必須保證服務提供者的區段和私用定義資訊會從登錄中移除。特別是，必須移除其 PPID 符合 dwPermanentProviderID 的 <[Provider<PPID>>] 區段，包括其 NumLines 和 NumPhones 專案。如果函式傳回成功，呼叫端必須負責從 [Providers] 區段中移除相符的 ProviderIDx 和 ProviderFilenamex 專案，並據以重新編號 [Providers] 區段中的其餘專案。

此程式必須讓系統保持一致狀態。它應該執行至完成，不允許使用者在部分完成時中止移除。如果移除失敗，提供者必須負責「退出」完成的工作並傳回錯誤。這可能表示在移除開始之前，預先掃描以確認可以移除完整移除。

當服務提供者正在使用 (時，可以在 TSPI_providerInit 與 TSPI_providerShutdown) 之間呼叫此函式。如果發生這種情況，服務提供者應該執行適當的組合來顯示使用者對話方塊，以宣告任何衝突並確認移除、將移除選項限制為透明執行，或發出 LINE_CLOSE 和 PHONE_CLOSE 訊息，通知TAPI和應用程式受影響的裝置已強制關閉以進行移除。在任何情況下，影響透過 TSPI 可見行為的任何變更，只有在服務提供者在下一 個TSPI_providerShutdown關閉時才會生效。

此函式不應該傳回LINEERR_INUSE或其他可能因為提供者正在使用應用程式而發生的錯誤;相反地，提供者應該直接與使用者授與此問題，然後在使用者決定中止作業時傳回LINEERR_OPERATIONFAILED。

在移除服務提供者時，只會呼叫此程式一次，直到呼叫 TSPI_providerInstall為止。呼叫者必須負責確保這一點。

1.4 版和更早版本中 Windows Telephony 提供的 Telephony 控制台公用程式會呼叫此函式， (符合外部順序需求，如叫用「移除」命令時所說明) 。

TAPI 層級沒有對應的函式。在該層級，應用程式預期已安裝服務提供者;否則，其線路和電話不會出現在裝置標識碼的可用序列內。執行中的應用程式會透過LINE_LINEDEVSTATE或PHONE_STATE訊息中的LINEDEVSTATE_REINIT或PHONESTATE_REINIT值，通知動態重新設定，包括移除服務提供者。