DiInstallDevice 函式 (newdev.h)

發行項
03/09/2024

DiInstallDevice 函式會在存在於系統中的指定裝置上安裝於驅動程式存放區中的指定驅動程式。

語法

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

參數

[in, optional] hwndParent

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

[in] DeviceInfoSet

裝置資訊集的句柄，其中包含代表指定裝置的裝置信息專案。

[in] DeviceInfoData

SP_DEVINFO_DATA 結構的指標，表示指定之裝置資訊集中的指定裝置。

[in, optional] DriverInfoData

SP_DRVINFO_DATA 結構的指標，指定要安裝在指定裝置上的驅動程式。這個參數是選擇性的，而且可以設定為 NULL。如果此參數為 NULL，DiInstallDevice 會搜尋驅動程式存放區中預安裝的驅動程式，找出最符合指定裝置的驅動程式，如果找到驅動程式，則會在指定的裝置上安裝驅動程式。

[in] Flags

DWORD 類型的值，指定零或下列旗標：

DIIDFLAG_SHOWSEARCHUI

如果呼叫端未指定驅動程式， (DriverInfoData 設定為 NULL) 且 DiInstallDevice 找不到符合指定裝置的預安裝驅動程式。 相反地，DiInstallDevice 會顯示裝置的 [找到新硬體精靈]。

DIIDFLAG_NOFINISHINSTALLUI

DiInstallDevice 不會啟動完成安裝精靈頁面或完成安裝動作。 DiInstallDevice 的呼叫端必須啟動這些作業。呼叫端只有在呼叫端要求在呼叫端提供的使用者介面元件內容中叫用完成安裝精靈頁面時，才應該指定這個旗標。

DIIDFLAG_INSTALLNULLDRIVER

DiInstallDevice 嘗試在指定的裝置上安裝 Null 驅動程式。如果設定此旗標， DiInstallDevice 不會使用 DriverInfoData 參數。 DiInstallDevice 會移除所有裝置設定，如果裝置無法以原始模式執行，函式會將裝置的狀態設定為 CM_PROB_FAILED_INSTALL。如果 DiInstallDevice 無法安裝 Null 驅動程式，則裝置的結果狀態與第一次連線到電腦且 Windows 找不到裝置的驅動程式相同。

DIIDFLAG_INSTALLCOPYINFDRIVERS

透過 CopyINF 指示詞指定的任何其他 INF 檔案，都會安裝在它適用的任何裝置上。安裝其他 INF 時發生的任何失敗都不會造成主要 INF 的安裝失敗。

[out, optional] NeedReboot

DiInstallDevice 所設定之 BOOL 類型的值指標，指出是否需要重新啟動系統才能完成安裝。這個參數是選擇性的，而且可以設定為 NULL。如果提供此參數且需要重新啟動系統才能完成安裝， DiInstallDevice 會將值設定為 TRUE。在此情況下，呼叫端會負責重新啟動系統。如果提供此參數且不需要系統重新啟動， DiInstallDevice 會將此參數設定為 FALSE。如果此參數為 NULL ，而且需要重新啟動系統才能完成安裝， DiInstallDevice 會顯示系統重新啟動對話方塊。

傳回值

如果函式已成功在指定的裝置上安裝指定的驅動程式，DiInstallDevice 會傳回 TRUE。否則， DiInstallDevice 會傳回 FALSE ，而且可以藉由呼叫 GetLastError 來擷取記錄的錯誤。 GetLastError 可能會傳回的一些較常見的錯誤值如下：

傳回碼	Description
ERROR_ACCESS_DENIED	呼叫端沒有系統管理員許可權。根據預設，Windows Vista 和 Windows Server 2008 要求呼叫程式具有系統管理員許可權，才能在裝置上安裝驅動程式。
ERROR_INVALID_FLAGS	針對 Flags 指定的值不是零或有效旗標的位 OR。
ERROR_IN_WOW64	呼叫應用程式是32位應用程式，嘗試在不允許的64位環境中執行。如需詳細資訊，請參閱在64位系統上安裝裝置。

備註

只有在需要在特定裝置上安裝特定驅動程式時，才呼叫 DiInstallDevice 。否則，請使用 UpdateDriverForPlugAndPlayDevices 或 DiInstallDriver 來安裝裝置的驅動程式。如需要呼叫哪些函式以在裝置上安裝驅動程式的詳細資訊，請參閱簡化驅動程式安裝的 SetupAPI 函式。

呼叫 DiInstallDevice 之前，呼叫端必須取得 SP_DEVINFO_DATA 結構來指定裝置，並選擇性地取得 SP_DRVINFO_DATA 結構來指定裝置的驅動程式。

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

呼叫 SetupDiGetClassDevs 以擷取包含裝置的裝置資訊集，然後呼叫 SetupDiEnumDeviceInfo 來列舉裝置資訊集中的裝置。每次呼叫時， SetupDiEnumDeviceInfo 都會傳回 SP_DEVINFO_DATA 結構，代表裝置資訊集中的列舉裝置。若要取得列舉裝置的特定資訊，請呼叫 SetupDiGetDeviceProperty 並提供 SetupDiEnumDeviceInfo 所傳回的SP_DEVINFO_DATA結構。
- 或 -
呼叫 SetupDiOpenDeviceInfo ，將具有已知裝置實例標識碼的裝置新增至裝置資訊集。 SetupDiOpenDeviceInfo 會傳回 SP_DEVINFO_DATA 結構，代表裝置資訊集中的裝置。

若要擷取所選驅動程式的SP_DRVINFO_DATA 結構，請呼叫 SetupDiBuildDriverInfoList 以建置裝置的驅動程式清單，然後呼叫 SetupDiEnumDriverInfo 以列舉裝置驅動程式清單的元素。針對每個列舉的驅動程式， SetupDiEnumDriverInfo 會擷取可識別驅動程式 的SP_DRVINFO_DATA 結構。您也可以呼叫 SetupDiGetDriverInfoDetail 來擷取列舉驅動程式的其他詳細數據。

一般而言，安裝應用程式應該將 NeedReboot 設定為 NULL。這可確保如果需要重新啟動才能完成安裝， DiInstallDevice 會提示使用者重新啟動系統。應用程式應該只在下列情況下提供 NeedReboot 指標：

應用程式必須呼叫 DiInstallDevice 數次才能完成安裝。在此情況下，應用程式應該記錄對 DiInstallDevice 的任何呼叫是否傳回 TRUENeedReboot 值，如果是的話，在最後呼叫 DiInstallDevice 傳回之後，提示使用者重新啟動系統。
應用程式必須在系統重新啟動之前執行必要的作業，而不是呼叫 DiInstallDevice。如果需要重新啟動系統，應用程式應該完成必要的作業，然後提示使用者重新啟動系統。
應用程式是類別安裝程式，在此情況下，類別安裝程式應該在裝置SP_DEVINSTALL_PARAMS結構的 Flags 成員中設定DI_NEEDREBOOT旗標。

規格需求

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