SetupDiInstallDevice 函式 (setupapi.h)

  • 發行項

SetupDiInstallDevice 函式是安裝要求DIF_INSTALLDEVICE的默認處理程式。

語法

WINSETUPAPI BOOL SetupDiInstallDevice(
  [in]      HDEVINFO         DeviceInfoSet,
  [in, out] PSP_DEVINFO_DATA DeviceInfoData
);

參數

[in] DeviceInfoSet

本機系統的 裝置資訊集 句柄，其中包含代表要安裝之裝置的裝置信息元素。

[in, out] DeviceInfoData

指定 DeviceInfoSet 中裝置資訊元素之SP_DEVINFO_DATA結構的指標。 這是 IN-OUT 參數，因為 DeviceInfoData。DevInst 可能會在傳回時使用新的句柄值來更新。

傳回值

如果函式成功，函式會傳回 TRUE 。 否則，它會傳回 FALSE ，而且可以透過呼叫 GetLastError 來擷取記錄的錯誤。

備註

SetupDiInstallDevice 會從 INF 檔案安裝驅動程式。 SetupAPI 的「驅動程式」定義實際上是「驅動程序節點」。因此，當此函式安裝驅動程式時，也會在下列清單中安裝專案：

  • 服務 (裝置的) 。
  • 驅動程式檔案。
  • 如果有任何) ，裝置特定的共同安裝程式 (。
  • 如果有任何) ，則屬性頁提供者 (。
  • 如果有任何) ，控制面板小程式 (。
此函式也會註冊任何必要的裝置介面。

成功的安裝包括但不限於下列步驟：

  • 在登錄中建立 驅動程式密鑰 ，並將適當的專案寫入 (，例如 InfPath 和 ProviderName) 。
  • 找出並處理裝置的 INF DDInstall 區段 。 區段可能是OS/架構特定的。 DDInstall 區段的 AddReg 和 DelReg 專案會導向裝置的軟體密鑰。 找出並處理 DDInstall。HW 區段的 AddReg 和 DelReg 專案會導向裝置 的硬體密鑰。 找出並處理 INF DDInstall.LogConfigOverride 區段，如果有的話，提供裝置的 覆寫 設定。 找出並處理 INF DDInstall.Services 區段 以新增裝置的服務 (，並可能移除不再需要的任何舊服務) 。
  • 將 INF 檔案複製到系統 INF 目錄。
  • 可能會根據裝置安裝參數中的旗標設定來執行其他檔案作業。

    如果DI_NOFILECOPY旗標和DI_NOVCP旗標 已清除，請執行 DDInstall 區段中指定的任何檔案作業。 如果已設定DI_NOVCP旗標，請將任何檔案作業排入佇列。

    如果已設定DI_NOFILECOPY旗標，請勿複製檔案。 例如，如果已針對此裝置安裝執行 DIF_INSTALLDEVICEFILES 作業，可能會設定此旗標。

  • 載入裝置的驅動程式。 這包括函式驅動程式和任何上層或下層篩選驅動程式。
  • 呼叫驅動程式的 AddDevice 例程。
  • 傳送 IRP_MN_START_DEVICE I/O 要求封包 (IRP) 來啟動裝置。
如果DI_NEEDRESTART、DI_NEEDREBOOT或DI_DONOTCALLCONFIGMG旗標是在 SP_DEVINSTALL_PARAMS 結構中 設定，Windows 就不會啟動裝置。

處理 DIF_INSTALLDEVICE 要求時，類別安裝程式應該傳回ERROR_DI_DO_DEFAULT或呼叫此函式。 此函式會針對裝置安裝執行許多工作，而且未來版本中可能會擴充工作清單。 如果類別安裝程式在沒有呼叫此函式的情況下執行裝置安裝，類別安裝程式可能無法在操作系統的未來版本上正確運作。

如果 Windows 找不到裝置的 INF 檔案，它會在嘗試安裝 Null 驅動程式時傳送DIF_INSTALLDEVICE。 只有在裝置支援原始模式或不是IoReportDetectedDevice) 所報告的非 PnP 裝置 (時，SetupDiInstallDevice 才會安裝 Null 驅動程式。 如需詳細資訊，請參閱 DIF_INSTALLDEVICE。

如果DI_FLAGSEX_SETFAILEDINSTALL旗標是在 SP_DEVINSTALL_PARAMS 結構中設定， 則 SetupDiInstallDevice 只會在裝置的 ConfigFlags 登錄值中設定 FAILEDINSTALL 旗標。

注意 只有 類別安裝程式 應該呼叫 SetupDiInstallDevice ，而且只有在類別安裝程式在 SetupDiInstallDevice 完成預設裝置安裝作業之後，才能執行裝置安裝作業。 在這種情況下，當安裝程式處理DIF_INSTALLDEVICE要求時，類別安裝程序必須直接呼叫 SetupDiInstallDevice 。 如需呼叫預設處理程式的詳細資訊，請參閱呼叫預設 DIF 程式代碼處理程式式。
 
SetupDiInstallDevice 的呼叫端必須是 Administrators 群組的成員。

規格需求

需求 值
最低支援的用戶端 可在 Microsoft Windows 2000 和更新版本的 Windows 中使用。
目標平台 桌面
標頭 setupapi.h (包括 Setupapi.h)
程式庫 Setupapi.lib
Dll Setupapi.dll

另請參閱

DIF_INSTALLDEVICE

SetupDiCallClassInstaller

SetupDiInstallDriverFiles