DiUninstallDevice 函式 (newdev.h)

DiUninstallDevice 函式會卸載裝置，並從系統移除其裝置節點 (devnode) 。 這與搭配使用 SetupDiCallClassInstaller 與 DIF_REMOVE 程式代碼不同，因為它除了呼叫時存在的子開發節點之外，還會嘗試卸載裝置節點。

在 Windows 8呼叫時不存在的任何子裝置都不會卸載。 不過，從 Windows 8 開始，將會卸載呼叫時不存在的任何子裝置。

語法

BOOL DiUninstallDevice(
  [in]            HWND             hwndParent,
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            DWORD            Flags,
  [out, optional] PBOOL            NeedReboot
);

參數

[in] hwndParent

最上層視窗的句柄，用來顯示與裝置卸載要求相關聯的任何使用者介面元件。 這個參數是選擇性的，而且可以設定為 NULL。

[in] DeviceInfoSet

包含 裝置資訊項目的裝置資訊集 句柄。 這個專案代表要透過此呼叫卸載的裝置。

[in] DeviceInfoData

SP_DEVINFO_DATA 結構的指標，表示執行卸載要求之指定裝置資訊集中的指定裝置。

[in] Flags

DWORD 類型的值，指定裝置卸載旗標。 從 Windows 7 開始，此參數必須設定為零。

[out, optional] NeedReboot

DiUninstallDevice 所設定之 BOOL 類型的值指標，指出是否需要重新啟動系統才能完成裝置卸載要求。 這個參數是選擇性的，而且可以設定為 NULL。

如果指定 參數且需要系統重新啟動， DiUninstallDevice 會將值設定為 TRUE。 在此情況下，應用程式必須提示使用者重新啟動系統。 如果提供此參數且不需要系統重新啟動， DiUninstallDevice 會將值設定為 FALSE。

如果此參數為 NULL ，而且需要重新啟動系統才能完成裝置卸載， DiUninstallDevice 會顯示系統重新啟動對話方塊。

如需此參數的詳細資訊，請參閱一節。

傳回值

如果函式已成功卸載代表裝置的最上層裝置節點，DiUninstallDevice 會傳回 TRUE。 否則， DiUninstallDevice 會傳回 FALSE，而且可以藉由呼叫 GetLastError 來擷取記錄的錯誤。 下列清單顯示 GetLastError 可能針對此 API 傳回的一些較常見的錯誤值：

傳回碼	Description
ERROR_ACCESS_DENIED	呼叫端沒有系統管理員許可權。 根據預設，Windows 要求呼叫者具有卸載裝置的系統管理員許可權。
ERROR_INVALID_FLAGS	為 Flags 參數指定的值不等於零。

 

注意 傳回值不表示移除所有子開發節點成功或失敗。 從 Windows Vista 開始， Setupapi.dev.log檔案中 提供移除子開發節點狀態的相關信息。 如需此檔案的詳細資訊，請參閱 SetupAPI 文字記錄。

 

備註

DiUninstallDevice 搭配DIF_REMOVE程序代碼使用時，會執行與 SetupDiCallClassInstaller 相同的函式。 主要差異在於也會刪除最上層裝置的子開發節點。 DiUninstallDevice 只有在最上層裝置節點無法卸載時才會傳回失敗，這與搭配DIF_REMOVE程式代碼使用時 SetupDiCallClassInstaller 的行為一致。 Setupapi.dev.log 檔案中是否有子開發節點卸載成功的詳細資訊。

要卸載的裝置是藉由提供包含所參考裝置的 裝置資訊集 ，以及特定裝置 的SP_DEVINFO_DATA 結構來指定。 這些是在 DeviceInfoSet 和 DeviceInfoData 參數中提供。

若要建立包含指定裝置的裝置資訊集，並取得裝置 的SP_DEVINFO_DATA 結構，請完成下列其中一項工作：

• 呼叫 SetupDiGetClassDevs 以擷取包含裝置的裝置資訊集，然後呼叫 SetupDiEnumDeviceInfo 來列舉裝置資訊集中的裝置。 每次呼叫時， SetupDiEnumDeviceInfo 都會傳回 SP_DEVINFO_DATA 結構，代表裝置資訊集中的列舉裝置。

  若要取得列舉裝置的特定資訊，請呼叫 SetupDiGetDeviceProperty 並提供 SetupDiEnumDeviceInfo 所傳回的SP_DEVINFO_DATA結構。

• 呼叫 SetupDiEnumDeviceInfo ，將具有已知裝置實例標識碼的裝置新增至裝置資訊集。 SetupDiOpenDeviceInfo 會傳回 SP_DEVINFO_DATA 結構，代表裝置資訊集中的裝置。

如果裝置卸載要求需要重新啟動計算機， DiUninstallDevice 會在 NeedReboot 參數設定為 NULL 時提示使用者重新啟動系統。 如果應用程式正在使用的任何使用者介面視窗， 則 hwndParent 參數應該設定為該視窗句柄的值。

不過，如果應用程式管理必要系統重新啟動的通知，則必須將 NeedReboot 參數設定為非NULL 值。 DiUninstallDevice 會根據是否需要系統重新啟動，將 NeedReboot 參數設定為 TRUE 或 FALSE。

下列清單顯示應用程式可能管理系統重新啟動的原因範例：

• 應用程式必須卸載數個裝置。 卸載所有裝置之後，如果對 DiUninstallDevice 的任何呼叫在 NeedReboot 參數中傳回 TRUE，應用程式應該會提示使用者重新啟動系統。
• 應用程式需要執行一些其他作業，才能重新啟動系統。 如果需要重新啟動系統，應用程式應該完成必要的作業，然後提示使用者重新啟動系統。
• 應用程式是類別安裝程式。 在此情況下，類別安裝程式應該在裝置SP_DEVINSTALL_PARAMS結構的 Flags 成員中設定DI_NEEDREBOOT旗標。

規格需求

需求	值
最低支援的用戶端	適用於 Windows 7 和更新版本的 Windows。
目標平台	桌面
標頭	newdev.h (包含 Newdev.h)
程式庫	Newdev.lib
Dll	Newdev.dll

另請參閱

DIF_REMOVE

裝置資訊集

SP_DEVINFO_DATA

SP_DEVINSTALL_PARAMS

SetupDiCallClassInstaller

SetupDiEnumDeviceInfo

SetupDiGetClassDevs

SetupDiGetDeviceProperty