SetupDiInstallDevice-Funktion (setupapi.h)

  • Artikel

Die SetupDiInstallDevice-Funktion ist der Standardhandler für die DIF_INSTALLDEVICE Installationsanforderung.

Syntax

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

Parameter

[in] DeviceInfoSet

Ein Handle für den Geräteinformationssatz für das lokale System, das ein Geräteinformationselement enthält, das das zu installierende Gerät darstellt.

[in, out] DeviceInfoData

Ein Zeiger auf eine SP_DEVINFO_DATA-Struktur , die ein Geräteinformationselement in DeviceInfoSet angibt. Dies ist ein IN-OUT-Parameter, da DeviceInfoData.DevInst kann bei der Rückgabe mit einem neuen Handle-Wert aktualisiert werden.

Rückgabewert

Die Funktion gibt TRUE zurück, wenn sie erfolgreich ist. Andernfalls wird FALSE zurückgegeben, und der protokollierte Fehler kann mit einem Aufruf von GetLastError abgerufen werden.

Hinweise

SetupDiInstallDevice installiert einen Treiber aus der INF-Datei. Die SetupAPI-Definition des "Treibers" ist tatsächlich ein "Treiberknoten". Wenn diese Funktion einen Treiber installiert, werden daher auch die Elemente in der folgenden Liste installiert:

  • Die Dienste für das Gerät.
  • Die Treiberdateien.
  • Gerätespezifische Co-Installer (falls vorhanden).
  • Eigenschaftenseitenanbieter (falls vorhanden).
  • Systemsteuerungs-Applets (falls vorhanden).
Diese Funktion registriert auch alle erforderlichen Geräteschnittstellen.

Eine erfolgreiche Installation umfasst die folgenden Schritte:

  • Erstellen Sie einen Treiberschlüssel in der Registrierung, und schreiben Sie entsprechende Einträge (z. B . InfPath und ProviderName).
  • Suchen und verarbeiten Sie den Abschnitt INF DDInstall für das Gerät. Der Abschnitt kann betriebssystem-/architekturspezifisch sein. Die AddReg- und DelReg-Einträge des Abschnitts DDInstall werden an den Softwareschlüssel des Geräts gerichtet. Suchen und verarbeiten Sie DDInstall. HW-Abschnitt , dessen AddReg - und DelReg-Einträge an den Hardwareschlüssel des Geräts gerichtet sind. Suchen und verarbeiten Sie den ABSCHNITT INF DDInstall.LogConfigOverride, falls vorhanden, um eine Außerkraftsetzungskonfiguration für das Gerät anzugeben. Suchen und verarbeiten Sie den ABSCHNITT INF DDInstall.Services , um Dienste für das Gerät hinzuzufügen (und möglicherweise alte Dienste zu entfernen, die nicht mehr benötigt werden).
  • Kopieren Sie die INF-Datei in das System-INF-Verzeichnis.
  • Möglicherweise führen Sie die anderen Dateivorgänge basierend auf den Flageinstellungen in den Geräteinstallationsparametern aus.

    Wenn das flag DI_NOFILECOPY und das flag DI_NOVCP eindeutig sind, führen Sie alle im Abschnitt DDInstall angegebenen Dateivorgänge aus. Wenn das DI_NOVCP-Flag festgelegt ist, stellen Sie alle Dateivorgänge in die Warteschlange.

    Wenn das flag DI_NOFILECOPY festgelegt ist, kopieren Sie die Dateien nicht. Dieses Flag kann festgelegt werden, wenn z. B. bereits ein DIF_INSTALLDEVICEFILES Vorgang für diese Geräteinstallation ausgeführt wurde.

  • Laden Sie die Treiber für das Gerät. Dies schließt den Funktionstreiber und alle Treiber für den oberen oder unteren Filter ein.
  • Rufen Sie die AddDevice-Routinen der Treiber auf.
  • Starten Sie das Gerät, indem Sie ein IRP_MN_START_DEVICE E/A-Anforderungspaket (IRP) senden.
Windows startet das Gerät nicht, wenn das flag DI_NEEDRESTART, DI_NEEDREBOOT oder DI_DONOTCALLCONFIGMG in der SP_DEVINSTALL_PARAMS-Struktur festgelegt ist.

Ein Klasseninstallationsprogramm sollte ERROR_DI_DO_DEFAULT zurückgeben oder diese Funktion aufrufen, wenn eine DIF_INSTALLDEVICE-Anforderung verarbeitet wird. Diese Funktion führt viele Aufgaben für die Geräteinstallation aus, und diese Aufgabenliste kann in zukünftigen Versionen erweitert werden. Wenn ein Klasseninstallationsprogramm die Geräteinstallation ausführt, ohne diese Funktion aufzurufen, funktioniert das Klasseninstallationsprogramm unter zukünftigen Versionen des Betriebssystems möglicherweise nicht ordnungsgemäß.

Wenn Windows keine INF-Datei für das Gerät finden kann, wird DIF_INSTALLDEVICE gesendet, um einen NULL-Treiber zu installieren. SetupDiInstallDevice installiert einen NULL-Treiber nur, wenn das Gerät den Raw-Modus unterstützt oder ein Nicht-PnP-Gerät ist (von IoReportDetectedDevice gemeldet). Weitere Informationen finden Sie unter DIF_INSTALLDEVICE.

Wenn das flag DI_FLAGSEX_SETFAILEDINSTALL in der SP_DEVINSTALL_PARAMS-Struktur festgelegt ist, legt SetupDiInstallDevice einfach das FAILEDINSTALL-Flag im Registrierungswert ConfigFlags des Geräts fest.

Hinweis Nur ein Klasseninstallationsprogramm sollte SetupDiInstallDevice aufrufen, und zwar nur in situationen, in denen das Klasseninstallationsprogramm Geräteinstallationsvorgänge ausführen muss, nachdem SetupDiInstallDevice den Standardinstallationsvorgang des Geräts abgeschlossen hat. In solchen Situationen muss das Klasseninstallationsprogramm SetupDiInstallDevice direkt aufrufen, wenn das Installationsprogramm eine DIF_INSTALLDEVICE-Anforderung verarbeitet. Weitere Informationen zum Aufrufen des Standardhandlers finden Sie unter Aufrufen von DIF-Standardcodehandlern.
 
Der Aufrufer von SetupDiInstallDevice muss Mitglied der Gruppe Administratoren sein.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Verfügbar in Microsoft Windows 2000 und höheren Versionen von Windows.
Zielplattform Desktop
Kopfzeile setupapi.h (schließen Sie Setupapi.h ein)
Bibliothek Setupapi.lib
DLL Setupapi.dll

Weitere Informationen

DIF_INSTALLDEVICE

SetupDiCallClassInstaller

SetupDiInstallDriverFiles