SP_DEVINSTALL_PARAMS_A-Struktur (setupapi.h)

Eine SP_DEVINSTALL_PARAMS-Struktur enthält Geräteinstallationsparameter, die einem bestimmten Geräteinformationselement oder global einem Geräteinformationssatz zugeordnet sind.

Syntax

typedef struct _SP_DEVINSTALL_PARAMS_A {
  DWORD             cbSize;
  DWORD             Flags;
  DWORD             FlagsEx;
  HWND              hwndParent;
  PSP_FILE_CALLBACK InstallMsgHandler;
  PVOID             InstallMsgHandlerContext;
  HSPFILEQ          FileQueue;
  ULONG_PTR         ClassInstallReserved;
  DWORD             Reserved;
  CHAR              DriverPath[MAX_PATH];
} SP_DEVINSTALL_PARAMS_A, *PSP_DEVINSTALL_PARAMS_A;

Member

cbSize

Die Größe der SP_DEVINSTALL_PARAMS-Struktur in Bytes.

Flags

Flags, die Installations- und Benutzeroberflächenvorgänge steuern. Einige Flags können vor dem Senden der Geräteinstallationsanforderung festgelegt werden, während andere Flags während der Verarbeitung einiger Anforderungen automatisch festgelegt werden. Flags können eine Kombination der folgenden Werte sein.

Die Flagwerte werden in Gruppen aufgeführt: schreibbar für Geräteinstallationsanwendungen und -installationsprogramme, schreibgeschützt (nur vom Betriebssystem festgelegt), reserviert und veraltet. Die erste Gruppe listet Flags auf, die schreibbar sind:

DI_CLASSINSTALLPARAMS

Legen Sie fest, dass die Klasseninstallationsparameter verwendet werden. SetupDiSetClassInstallParams legt dieses Flag fest, wenn der Aufrufer Parameter angibt, und löscht das Flag, wenn der Aufrufer einen NULL-Parameterzeiger angibt.

DI_COMPAT_FROM_CLASS

Legen Sie fest, um setupDiBuildDriverInfoList zu erzwingen, die Liste der kompatiblen Treiber eines Geräts aus der Klassentreiberliste anstelle der INF-Datei zu erstellen.

DI_DRIVERPAGE_ADDED

Wird von einem Klasseninstaller oder Co-Installer festgelegt, wenn das Installationsprogramm eine Seite bereitstellt, die die vom System bereitgestellte Treibereigenschaftenseite ersetzt. Wenn dieses Flag festgelegt ist, zeigt das Betriebssystem die vom System bereitgestellte Treiberseite nicht an.

DI_DONOTCALLCONFIGMG

Legen Sie fest, ob der Konfigurations-Manager nicht aufgerufen werden soll, um Geräte während der Ausführung bestimmter Geräteinstallationsfunktionen (z. B. SetupDiInstallDevice) zu entfernen oder erneut aufzulisten.

Wenn dieses Flag festgelegt ist, dürfen Geräteinstallationsanwendungen, Klasseninstaller und Co-Installer nicht die folgenden Funktionen aufrufen:

CM_Reenumerate_DevNodeCM_Reenumerate_DevNode_ExCM_Query_And_Remove_SubTree CM_Query_And_Remove_SubTree_ExCM_Setup_DevNode CM_Setup_DevNode_ExCM_Set_HW_Prof_Flags CM_Set_HW_Prof_Flags_ExCM_Enable_DevNode CM_Enable_DevNode_Ex CM_Disable_DevNodeCM_Disable_DevNode_Ex

DI_ENUMSINGLEINF

Legen Sie fest, ob Installationsprogramme und andere Geräteinstallationskomponenten nur die durch SP_DEVINSTALL_PARAMS angegebene INF-Datei durchsuchen sollen. DriverPath. Wenn dieses Flag festgelegt ist, enthält DriverPath den Pfad einer einzelnen INF-Datei anstelle eines Pfads eines Verzeichnisses.

DI_INF_IS_SORTED

Legen Sie fest, um anzugeben, dass auf der Seite Gerät auswählen Treiber in der Reihenfolge aufgelistet werden sollen, in der sie in der INF-Datei angezeigt werden, anstatt sie alphabetisch zu sortieren.

DI_INSTALLDISABLED

Legen Sie fest, ob das Gerät standardmäßig in einem deaktivierten Zustand installiert werden soll. Um erkannt zu werden, muss dieses Flag festgelegt werden, bevor Windows den Standardhandler für die DIF_INSTALLDEVICE-Anforderung aufruft.

DI_NEEDREBOOT

Bei NT-basierten Betriebssystemen wird dieses Flag festgelegt, wenn das Gerät erfordert, dass der Computer nach der Geräteinstallation oder einer Änderung des Gerätezustands neu gestartet werden muss. Ein Klasseninstaller oder Co-Installer kann dieses Flag jederzeit während der Geräteinstallation festlegen, wenn das Installationsprogramm feststellt, dass ein Neustart erforderlich ist.

DI_NEEDRESTART

Identisch mit DI_NEEDREBOOT.

DI_NOBROWSE

Legen Sie fest, um das Browsen zu deaktivieren, wenn der Benutzer einen OEM-Datenträgerpfad auswählt. Eine Geräteinstallationsanwendung legt dieses Flag fest, um einen Benutzer darauf zu beschränken, nur die Installation über den Installationsmedienspeicherort durchzuführen.

DI_NODI_DEFAULTACTION

Legen Sie fest, ob SetupDiCallClassInstaller keine Standardaktion ausführen soll, wenn der Klasseninstaller ERR_DI_DO_DEFAULT zurückgibt oder kein Klasseninstallationsprogramm vorhanden ist.

DI_NOFILECOPY

Legen Sie fest, ob Geräteinstallationsanwendungen und -komponenten, z. B. SetupDiInstallDevice, das Kopieren von Dateien überspringen sollen.

DI_NOVCP

Legen Sie fest, um die Erstellung einer neuen Kopierwarteschlange zu deaktivieren. Verwenden Sie die vom Aufrufer bereitgestellte Kopierwarteschlange in SP_DEVINSTALL_PARAMS. FileQueue.

DI_NOWRITE_IDS

Legen Sie fest, um zu verhindern, dass SetupDiInstallDevice die INF-angegebenen Hardware-IDs und kompatiblen IDs in die Geräteeigenschaften für den Geräteknoten (devnode) schreibt. Dieses Flag sollte nur für root-enumerierte Geräte festgelegt werden.

Dieses Flag überschreibt das flag DI_FLAGSEX_ALWAYSWRITEIDS.

DI_PROPERTIES_CHANGE

Legen Sie Geräte-Manager fest, ob die Eigenschaften eines Geräts geändert wurden, was eine Aktualisierung der Benutzeroberfläche des Installationsprogramms erfordert.

DI_QUIETINSTALL

Legen Sie fest, ob die Geräteinstallationsfunktionen im Hintergrund ausgeführt werden müssen, und verwenden Sie nach Möglichkeit Standardoptionen. Klasseninstaller und Co-Installer dürfen keine Benutzeroberfläche anzeigen, wenn dieses Flag festgelegt ist.

DI_RESOURCEPAGE_ADDED

Wird von einem Klasseninstaller oder Co-Installer festgelegt, wenn das Installationsprogramm eine Seite bereitstellt, die die vom System bereitgestellte Ressourceneigenschaftenseite ersetzt. Wenn dieses Flag festgelegt ist, zeigt das Betriebssystem die vom System bereitgestellte Ressourcenseite nicht an.

DI_SHOWOEM

Legen Sie fest, um die Unterstützung für OEM-Datenträger zuzulassen. Wenn dieses Flag festgelegt ist, zeigt das Betriebssystem auf der Seite Gerät auswählen die Schaltfläche "Datenträger haben" an. Dieses Flag wird standardmäßig in vom System bereitgestellten Assistenten festgelegt.

DI_USECI_SELECTSTRINGS

Legen Sie fest, ob ein Klasseninstallationsprogramm oder ein Co-Installer Zeichenfolgen bereitgestellt hat, die während setupDiSelectDevice verwendet werden sollen.

Die folgenden Flags sind schreibgeschützt (nur vom Betriebssystem festgelegt):

DI_DIDCLASS

Legen Sie fest, ob SetupDiBuildDriverInfoList bereits eine Liste der Treiber für diese Geräteklasse erstellt hat. Wenn diese Liste bereits erstellt wurde, enthält sie alle Treiberinformationen, und dieses Flag ist immer festgelegt. SetupDiDestroyDriverInfoList löscht dieses Flag, wenn es eine Liste von Treibern für eine Klasse löscht.

Dieses Flag ist schreibgeschützt. Dieses Flag wird nur vom Betriebssystem festgelegt.

DI_DIDCOMPAT

Legen Sie fest, ob SetupDiBuildDriverInfoList bereits eine Liste kompatibler Treiber für dieses Gerät erstellt hat. Wenn diese Liste bereits erstellt wurde, enthält sie alle Treiberinformationen, und dieses Flag ist immer festgelegt. SetupDiDestroyDriverInfoList löscht dieses Flag, wenn eine liste kompatibler Treiber gelöscht wird.

Dieses Flag wird nur in Geräteinstallationsparametern festgelegt, die einem bestimmten Geräteinformationselement zugeordnet sind, nicht in Parametern für eine Geräteinformation als Ganzes.

Dieses Flag ist schreibgeschützt. Dieses Flag wird nur vom Betriebssystem festgelegt.

DI_MULTMFGS

Legen Sie durch SetupDiBuildDriverInfoList fest , wenn eine Liste von Treibern für eine Gerätesetupklasse Treiber enthält, die von mehreren Herstellern bereitgestellt werden.

Dieses Flag ist schreibgeschützt. Dieses Flag wird nur vom Betriebssystem festgelegt.

Die folgenden Flags sind reserviert:

DI_AUTOASSIGNRES

DI_DISABLED

DI_FORCECOPY

DI_GENERALPAGE_ADDED

DI_OVERRIDE_INFFLAGS

DI_SHOWALL

DI_SHOWCLASS

DI_SHOWCOMPAT

Die folgenden Flags sind veraltet:

DI_NOSELECTICONS

DI_PROPS_NOCHANGEUSAGE

FlagsEx

Zusätzliche Flags, die die Steuerung der Installations- und Benutzeroberflächenvorgänge ermöglichen. Einige Flags können vor dem Aufrufen der Geräteinstallationsfunktionen festgelegt werden, während andere Flags während der Verarbeitung einiger Funktionen automatisch festgelegt werden. FlagsEx kann eine Kombination der folgenden Werte sein.

Die Flagwerte werden in Gruppen aufgeführt: schreibbar für Geräteinstallationsanwendungen und -installationsprogramme, schreibgeschützt (nur vom Betriebssystem festgelegt), reserviert und veraltet.

Die erste Gruppe listet Flags auf, die schreibbar sind:

DI_FLAGSEX_ALLOWEXCLUDEDDRVS

Wenn festgelegt, schließen Sie Treiber ein, die als "Von Auswahl ausschließen" gekennzeichnet waren.

Wenn z. B. dieses Flag festgelegt ist, zeigt SetupDiSelectDevice Treiber an, die den Status "Von Auswahl ausschließen" aufweisen, und SetupDiBuildDriverInfoList enthält in der Liste der angeforderten Treiber "Aus Auswählen ausschließen".

Ein Treiber ist "Exclude From Select", wenn er entweder in der INF-Datei als ExcludeFromSelect gekennzeichnet ist, oder es ist ein Treiber für ein Gerät, dessen gesamte Setupklasse im Klasseninstallationsprogramm INF als NoInstallClass oder NoUseClass gekennzeichnet ist. Treiber für PnP-Geräte sind in der Regel "Von Auswahl ausschließen"; PnP-Geräte sollten nicht manuell installiert werden. Um eine Liste der Treiberdateien für ein PnP-Gerät zu erstellen, muss ein Aufrufer von SetupDiBuildDriverInfoList dieses Flag festlegen.

DI_FLAGSEX_ALWAYSWRITEIDS

Wenn festgelegt und das flag DI_NOWRITE_IDS eindeutig ist, schreiben Sie immer Hardware und kompatible IDs in die Geräteeigenschaften für den Devnode. Dieses Flag sollte nur für root-enumerierte Geräte festgelegt werden.

DI_FLAGSEX_APPENDDRIVERLIST

Wenn festgelegt, fügt SetupDiBuildDriverInfoList eine neue Treiberliste an eine vorhandene Liste an. Dieses Flag ist bei der Suche nach mehreren Speicherorten relevant.

DI_FLAGSEX_DRIVERLIST_FROM_URL

Falls festgelegt, erstellen Sie die Treiberliste aus INF(en), die aus der url abgerufen werden, die in SP_DEVINSTALL_PARAMS angegeben ist. DriverPath. Wenn driverPath eine leere Zeichenfolge ist, verwenden Sie die Windows Update Website.

Derzeit unterstützt das Betriebssystem keine URLs. Verwenden Sie dieses Flag, um SetupDiBuildDriverInfoList anweisen, die Windows Update Website zu durchsuchen.

Legen Sie dieses Flag nicht fest, wenn DI_QUIETINSTALL festgelegt ist.

DI_FLAGSEX_EXCLUDE_OLD_INET_DRIVERS

Wenn festgelegt, schließen Sie beim Erstellen einer Treiberliste keine alten Internettreiber ein. Dieses Flag sollte jedes Mal festgelegt werden, wenn Sie eine Liste mit potenziellen Treibern für ein Gerät erstellen. Sie können dieses Flag deaktivieren, wenn Sie nur eine Liste der Treiber erhalten, die derzeit für ein Gerät installiert sind.

DI_FLAGSEX_FILTERCLASSES

Wenn festgelegt, sucht SetupDiBuildClassInfoList nach Klasseneinschlussfiltern. Dies bedeutet, dass ein Gerät nicht in die Klassenliste aufgenommen wird, wenn seine Klasse als NoInstallClass gekennzeichnet ist.

DI_FLAGSEX_FILTERSIMILARDRIVERS

(Windows XP und höher.) Wenn festgelegt, enthält SetupDiBuildDriverInfoList beim Erstellen einer Klassentreiberliste "ähnliche" Treiber. Ein "ähnlicher" Treiber ist einer, für den eine der Hardware-IDs oder kompatiblen IDs in der INF-Datei teilweise (oder vollständig) mit einer der Hardware-IDs oder kompatiblen IDs der Hardware übereinstimmt.

DI_FLAGSEX_FINISHINSTALL_ACTION

(Windows Vista und höher.) Weitere Informationen finden Sie unter Markieren eines Geräts mit einer Finish-Install auszuführenden Aktion .

DI_FLAGSEX_INET_DRIVER

Wenn festgelegt, wurde der Treiber aus dem Internet abgerufen. Windows verwendet die INF des Geräts nicht, um zukünftige Geräte zu installieren, da Windows nicht garantieren kann, dass die Treiberdateien erneut aus dem Internet abgerufen werden können.

DI_FLAGSEX_INSTALLEDDRIVER

(Windows XP und höher.) Wenn festgelegt, enthält SetupDiBuildDriverInfoList beim Erstellen einer Liste von Klassentreibern oder gerätekompatiblen Treibern nur den aktuell installierten Treiber.

DI_FLAGSEX_NO_CLASSLIST_NODE_MERGE

(Windows XP und höher.) Wenn festgelegt, führt SetupDiBuildDriverInfoList beim Erstellen einer Liste von Klassentreibern keine Knoten in der Treiberliste zusammen, die aus demselben INF stammen und die gleiche Treiberbeschreibung und Rangfolge aufweisen.

DI_FLAGSEX_NO_DRVREG_MODIFY

Verarbeiten Sie die AddReg - und DelReg-Einträge für die Hardware- und Softwareschlüssel (Treiber) des Geräts nicht. Dies sind die AddReg - und DelReg-Einträge in den INF-Dateien DDInstall und DDInstall. HW-Abschnitte .

DI_FLAGSEX_POWERPAGE_ADDED

Wenn diese Einstellung festgelegt ist, hat ein Installationsprogramm eine eigene Seite für das Dialogfeld mit den Energieeigenschaften hinzugefügt. Das Betriebssystem zeigt die seite mit den vom System bereitgestellten Energieeigenschaften nicht an. Dieses Flag ist nur relevant, wenn das Gerät die Energieverwaltung unterstützt.

DI_FLAGSEX_PROPCHANGE_PENDING

Wenn festgelegt, hat der Benutzer Änderungen an einem oder mehreren Geräteeigenschaftenblättern vorgenommen. Der Eigenschaftenseitenanbieter legt dieses Flag in der Regel fest.

Wenn der Benutzer das Geräteeigenschaftenblatt schließt, überprüft Geräte-Manager das flag DI_FLAGSEX_PROPCHANGE_PENDING. Wenn sie festgelegt ist, löscht Geräte-Manager dieses Flag, legt das flag DI_PROPERTIES_CHANGE fest und sendet eine DIF_PROPERTYCHANGE-Anforderung an die Installationsprogramme, um sie darüber zu informieren, dass sich etwas geändert hat.

DI_FLAGSEX_RECURSIVESEARCH

(Windows Vista und höher.) Wenn festgelegt, wird die Suche rekursiv ausgeführt, wenn SetupDiBuildDriverInfoList nach INFs in dem pfad sucht, der im DriverPath-Wert angegeben ist.

DI_FLAGSEX_SEARCH_PUBLISHED_INFS

(Windows Vista und höher.) Falls festgelegt, wird die Suche nur auf INFs beschränkt, die in den Treiberspeicher importiert wurden, wenn setupDiBuildDriverInfoList verwendet wird, um nach INFs zu suchen, ohne dass ein INF-Pfad oder Suchpfad angegeben ist.

DI_FLAGSEX_SETFAILEDINSTALL

Legen Sie fest, ob bei der Installation ein Fehler aufgetreten ist. Wenn dieses Flag festgelegt ist, legt die SetupDiInstallDevice-Funktion nur das FAILEDINSTALL-Flag im ConfigFlags-Registrierungswert des Geräts fest. Wenn DI_FLAGSEX_SETFAILEDINSTALL festgelegt ist, müssen Co-Installer NO_ERROR als Reaktion auf DIF_INSTALLDEVICE zurückgeben, während Klasseninstaller NO_ERROR oder ERROR_DI_DO_DEFAULT zurückgeben müssen.

DI_FLAGSEX_USECLASSFORCOMPAT

Filtern Sie INF-Dateien nach der Setupklasse des Geräts, wenn Sie eine Liste mit kompatiblen Treibern erstellen. Wenn die Setupklasse eines Geräts bekannt ist, reduziert das Festlegen dieses Flags die Zeit, die zum Erstellen einer Liste kompatibler Treiber beim Durchsuchen von NICHT vorkompilierten INF-Dateien erforderlich ist. Dieses Flag wird ignoriert, wenn DI_COMPAT_FROM_CLASS festgelegt ist.

Die folgenden Flags sind schreibgeschützt: nur das Betriebssystem legt diese Flags fest:

DI_FLAGSEX_CI_FAILED

Wird vom Betriebssystem festgelegt, wenn ein Klasseninstallationsprogramm nicht geladen oder gestartet werden konnte. Dieses Flag ist schreibgeschützt.

DI_FLAGSEX_DIDCOMPATINFO

Windows hat eine Liste der Treiberknoten erstellt, die mit dem Gerät kompatibel sind. Dieses Flag ist schreibgeschützt.

DI_FLAGSEX_DIDINFOLIST

Windows hat eine Liste von Treiberknoten erstellt, die alle Treiber enthält, die in den INF-Dateien der angegebenen Setupklasse aufgeführt sind. Wenn die angegebene Setupklasse NULL ist, weil der HDEVINFO-Satz oder das Gerät über keine zugeordnete Klasse verfügt, enthält die Liste alle Treiberknoten aus allen verfügbaren INF-Dateien. Dieses Flag ist schreibgeschützt.

DI_FLAGSEX_IN_SYSTEM_SETUP

Wenn festgelegt, erfolgt die Installation während der anfänglichen Systemeinrichtung. Dieses Flag ist schreibgeschützt.

Die folgenden Flags sind reserviert und sollten nicht verwendet werden:

DI_FLAGSEX_ALTPLATFORM_DRVSEARCH

DI_FLAGSEX_BACKUPONREPLACE

DI_FLAGSEX_DEVICECHANGE

DI_FLAGSEX_OLDINF_IN_CLASSLIST

DI_FLAGSEX_PREINSTALLBACKUP

DI_FLAGSEX_RESTART_DEVICE_ONLY

DI_FLAGSEX_USEOLDINFSEARCH

Die folgenden Flags sind veraltet:

DI_FLAGSEX_AUTOSELECTRANK0

DI_FLAGSEX_NOUIONQUERYREMOVE

hwndParent

Fensterhandle, das die Benutzeroberflächendialoge im Zusammenhang mit diesem Gerät besitzt.

InstallMsgHandler

Rückruf, der verwendet wird, um Ereignisse während des Kopierens von Dateien zu behandeln. Ein Installationsprogramm kann beispielsweise einen Rückruf verwenden, um beim Committen einer Dateiwarteschlange eine spezielle Verarbeitung auszuführen.

InstallMsgHandlerContext

Private Daten, die vom InstallMsgHandler-Rückruf verwendet werden.

FileQueue

Ein Handle für eine vom Aufrufer bereitgestellte Dateiwarteschlange, in der Dateivorgänge in die Warteschlange eingereiht, aber kein Commit ausgeführt werden sollen.

Wenn Sie eine Dateiwarteschlange einem Geräteinformationssatz (SetupDiSetDeviceInstallParams) zuordnen, müssen Sie die Zuordnung der Warteschlange zum Geräteinformationssatz aufheben, bevor Sie den Geräteinformationssatz löschen. Wenn Sie die Zuordnung der Dateiwarteschlange nicht aufheben können, kann Windows die Verweisanzahl für den Geräteinformationssatz nicht verringern und den Arbeitsspeicher nicht freigeben.

Diese Warteschlange wird nur verwendet, wenn das flag DI_NOVCP festgelegt ist, was angibt, dass Dateivorgänge in die Warteschlange eingereiht, aber kein Commit ausgeführt werden sollen.

ClassInstallReserved

Ein Zeiger für Klasseninstallationsdaten. Co-Installer dürfen dieses Feld nicht verwenden.

Reserved

Reserviert. Nur zur internen Verwendung.

DriverPath[MAX_PATH]

Dieser Pfad wird von der Funktion SetupDiBuildDriverInfoList verwendet.

Hinweise

Hinweis

Der setupapi.h-Header definiert SP_DEVINSTALL_PARAMS als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung Wert
Header setupapi.h (einschließlich Setupapi.h)

Weitere Informationen

SetupDiBuildClassInfoList

SetupDiBuildDriverInfoList

SetupDiCallClassInstaller

SetupDiGetDeviceInstallParams

SetupDiInstallDevice

SetupDiSelectDevice

SetupDiSetDeviceInstallParams