DIF_SELECTDEVICE

Artikel
06/15/2023

Eine DIF_SELECTDEVICE-Anforderung ermöglicht es einem Installationsprogramm, an der Auswahl des Treibers für ein Gerät teilzunehmen.

Sendebedingungen

Wenn Sie einen Treiber für ein neu aufgezähltes Gerät oder einen neuen Treiber für ein vorhandenes Gerät auswählen (Treiber wechseln). Wenn ein Benutzer beispielsweise Hardware hinzufügen/entfernen auswählt und die Modemklasse auswählt. Oder ein Benutzer fügt ein PnP-Gerät ein und wählt im Assistenten zum Suchen neuer Hardware die Option "Treiber aus einer Liste auswählen".

Wer behandelt

Klassen-Co-Installer	Kann verarbeiten
Geräte-Co-Installer	Behandelt nicht
Klasseninstallationsprogramm	Kann verarbeiten

Eingabe des Installationsprogramms

DeviceInfoSet
Stellt ein Handle für den Geräteinformationssatz bereit, der das Gerät enthält, für das ein Treiber ausgewählt werden soll. Dem DeviceInfoSet ist eine Gerätesetupklasse zugeordnet.

DeviceInfoData
Stellt optional einen Zeiger auf eine SP_DEVINFO_DATA-Struktur bereit, die das Gerät im Geräteinformationssatz identifiziert.

Wenn DeviceInfoDataNULL ist, wird mit dieser Anforderung ein Treiber für die Gerätesetupklasse ausgewählt, die deviceInfoSet zugeordnet ist.

Geräteinstallationsparameter
Wenn DeviceInfoData nicht NULL ist, sind Geräteinstallationsparameter (SP_DEVINSTALL_PARAMS) mit DeviceInfoData verknüpft. Wenn DeviceInfoDataNULL ist, sind Geräteinstallationsparameter dem DeviceInfoSet zugeordnet.

Von besonderem Interesse ist der DriverPath, der den Speicherort von INF(s) enthält, die beim Erstellen der Treiberliste verwendet werden sollen.

Klasseninstallationsparameter
Eine SP_SELECTDEVICE_PARAMS-Struktur ist deviceInfoData zugeordnet, wenn DeviceInfoData nicht NULL ist. Andernfalls werden die Klasseninstallationsparameter dem Geräteinformationssatz als Ganzes zugeordnet.

Installationsprogrammausgabe

Geräteinstallationsparameter
Ein Installationsprogramm kann die Geräteinstallationsparameter ändern. Das DriverPath-Feld sollte jedoch nicht geändert werden.

Klasseninstallationsparameter
Ein Installationsprogramm kann die SP_SELECTDEVICE_PARAMS ändern. Beispielsweise kann ein Installationsprogramm einen Titel und/oder Anweisungen für Windows angeben, die im Dialogfeld verwendet werden sollen, in dem der Benutzer aufgefordert wird, einen Treiber auszuwählen.

Wenn ein Installationsprogramm neue Select-Device-Parameter festlegt und die von einem vorherigen Installationsprogramm festgelegten Parameter ändert, muss das Installationsprogramm die Felder nullen, die es nicht festlegt.

Rückgabewert des Installers

Wenn ein Co-Installer nichts für diesen DIF-Code ausführt, gibt es NO_ERROR aus seinem Vorverarbeitungsdurchlauf zurück. Wenn ein Co-Installer diesen DIF-Code verarbeitet, sollte er dies im Vorverarbeitungsdurchlauf tun und NO_ERROR oder einen Win32-Fehlercode zurückgeben. Zu dem Zeitpunkt, zu dem ein Co-Installer für die Nachverarbeitung aufgerufen wird, wurde der Treiber bereits ausgewählt.

Wenn ein Klasseninstallationsprogramm diese Anforderung erfolgreich verarbeitet und SetupDiCallClassInstaller anschließend den Standardhandler aufrufen sollte, gibt das Klasseninstallationsprogramm ERROR_DI_DO_DEFAULT zurück.

Wenn der Klasseninstaller diese Anforderung erfolgreich verarbeitet, einschließlich des direkten Aufrufs des Standardhandlers, sollte der Klasseninstaller NO_ERROR zurückgeben, und SetupDiCallClassInstaller ruft den Standardhandler anschließend nicht mehr auf.

Hinweis Der Klasseninstaller kann den Standardhandler direkt aufrufen, aber der Klasseninstaller sollte niemals versuchen, die Vorgänge des Standardhandlers abzulösen.

Weitere Informationen zum Aufrufen des Standardhandlers finden Sie unter Aufrufen von DIF-Standardcodehandlern.

Wenn beim Klasseninstallationsprogramm ein Fehler auftritt, sollte das Installationsprogramm einen entsprechenden Win32-Fehlercode zurückgeben, und SetupDiCallClassInstaller ruft anschließend nicht den Standardhandler auf.

Ein Klasseninstallationsprogramm gibt ERROR_DI_BAD_PATH zurück, wenn der DriverPath-Member der entsprechenden SP_DEVINSTALL_PARAMS-Struktur nicht gleich NULL ist, aber keine gültigen Treiber am angegebenen Pfadspeicherort vorhanden sind. Dies kann auftreten, wenn keine Treiber am Pfadspeicherort vorhanden sind oder Treiber vorhanden sind, aber das Flags-Element der SP_DRVINSTALL_PARAMS-Struktur jedes Treibers mit dem flag DN_BAD_DRIVER festgelegt wurde. Als Reaktion auf diesen Fehlercode zeigt Windows dem Benutzer einen Fehler an.

Standard-DIF-Codehandler

SetupDiSelectDevice

Installer-Vorgang

Als Reaktion auf eine DIF_SELECTDEVICE-Anforderung führt ein Installationsprogramm alle Auswahlvorgänge aus, die für sein Gerät oder seine Geräteklasse erforderlich sind, zusätzlich zu den Aufgaben des Standardhandlers. Ein Installationsprogramm antwortet auf diese DIF-Anforderung in der Regel auf eine der folgenden Arten:

Sie unternehmen nichts.

Wenn ein Installationsprogramm keine speziellen Auswahlanforderungen hat, tut es nichts als Reaktion auf diesen DIF-Code. Ein Klasseninstallationsprogramm gibt ERROR_DI_DO_DEFAULT zurück, und ein Co-Installer gibt NO_ERROR zurück.
Geben Sie Select-Zeichenfolgen an, die Windows auf der Auswahl-Benutzeroberfläche anzeigt.

Ein Installationsprogramm kann ausgewählte Zeichenfolgen in den Klasseninstallationsparametern (SP_SELECTDEVICE_PARAMS) bereitstellen. Beispielsweise kann ein Installationsprogramm die Anweisungen oder den Titel des Fensters ändern.

Ein Klasseninstallationsprogramm sollte keine Auswahlzeichenfolgen bereitstellen, wenn ein Co-Installer bereits Select-Zeichenfolgen bereitgestellt hat. Der Co-Installer hat wahrscheinlich relevantere Informationen.

Wenn ein Installationsprogramm die SP_SELECTDEVICE_PARAMS ändert, muss das Installationsprogramm auch das flag DI_USECI_SELECTSTRINGS im SP_DEVINSTALL_PARAMS festlegen.

Wenn ein Installationsprogramm erfolgreich ausgewählte Zeichenfolgen bereitstellt, muss Windows weiterhin den Standardhandler aufrufen. Daher gibt in diesem Fall ein Co-Installer NO_ERROR und ein Klasseninstallationsprogramm ERROR_DI_DO_DEFAULT zurück.
Ändern Sie die Geräteinstallationsparameter.

Ein Installationsprogramm kann die Geräteinstallationsparameter (SP_DEVINSTALL_PARAMS) ändern. Beispielsweise kann ein Installationsprogramm das DI_SHOWOEM-Flag so festlegen, dass Windows die Schaltfläche Datenträger haben anzeigt.

Wenn ein Klasseninstallationsprogramm die Geräteinstallationsparameter erfolgreich ändert, gibt der Klasseninstaller ERROR_DI_DO_DEFAULT zurück.
Ändern Sie die Liste der Treiber, aus denen der Benutzer auswählen kann.

Diese Aktion ist weniger häufig, aber möglich. Ein Installationsprogramm, das die Treiberliste ändert, liefert möglicherweise auch Ausgewählte Zeichenfolgen.

Ein Installationsprogramm, das die Treiberliste ändert, markiert in der Regel Treiber, die für das Gerät ungeeignet sind. Ein Installationsprogramm markiert solche Treiber mit dem Flag DNF_BAD_DRIVER. Windows lässt diese Treiber in der Liste aus, die dem Benutzer angezeigt wird.

Ein Installationsprogramm markiert fehlerhafte Treiber, indem es die folgenden Schritte ausführt:
1. Erstellen Sie die Treiberliste, indem Sie SetupDiBuildDriverInfoList mit dem DriverType SPDIT_CLASSDRIVER aufrufen.
2. Rufen Sie die Informationen zum ersten Treiber in der Liste ab, indem Sie SetupDiEnumDriverInfo und SetupDiGetDriverInstallParams aufrufen. Wenn der Treiber nicht für das Gerät geeignet ist, legen Sie das DNF_BAD_DRIVER-Flag im Feld Flags der Parameter fest. Wenden Sie die Änderung auf die Parameter an, indem Sie SetupDiSetDriverInstallParams aufrufen.
3. Wiederholen Sie den vorherigen Schritt, bis Sie alle Treiber in der Liste verarbeitet haben. Stellen Sie sicher, dass Sie den MemberIndex-Parameter auf SetupDiEnumDriverInfo erhöhen, wie auf der Referenzseite für diese Funktion beschrieben.
Ein Installationsprogramm kann das DNF_BAD_DRIVER-Flag für einen oder mehrere Treiber in der Treiberliste festlegen, aber ein Installationsprogramm darf dieses Flag nicht löschen.

Wenn ein oder mehrere Installationsprogramme die Treiberliste erfolgreich ändern, muss Windows weiterhin den Standardhandler aufrufen. Daher gibt in diesem Fall ein Co-Installer NO_ERROR und ein Klasseninstallationsprogramm ERROR_DI_DO_DEFAULT zurück.
Zeigen Sie eine eigene Benutzeroberfläche für die Treiberauswahl an, und legen Sie den ausgewählten Treiber fest.

Nur ein Klasseninstallationsprogramm kann eine eigene Benutzeroberfläche für die Treiberauswahl anzeigen. Co-Installer dürfen nicht. Beispielsweise kann ein Klasseninstallationsprogramm Anstelle von Textlisten Bilder anzeigen.

Wenn der Klasseninstaller den ausgewählten Treiber erfolgreich festlegt, gibt der Klasseninstaller NO_ERROR zurück, und Windows ruft den Standardhandler nicht auf und zeigt daher nicht die Standardauswahlschnittstelle an.

Wenn das flag DI_ENUMSINGLEINF in den Geräteinstallationsparametern festgelegt ist, ist DriverPath ein Pfad einer einzelnen INF-Datei und nicht ein Pfad eines Verzeichnisses. Ein Installationsprogramm darf nur dieses einzelne INF verwenden, um die Treiberliste zu erstellen.

Weitere Informationen zu DIF-Codes finden Sie unter Behandeln von DIF-Codes.