SetupDiRegisterDeviceInfo-Funktion (setupapi.h)

  • Artikel

Die SetupDiRegisterDeviceInfo-Funktion ist der Standardhandler für die DIF_REGISTERDEVICE Anforderung.

Syntax

WINSETUPAPI BOOL SetupDiRegisterDeviceInfo(
  [in]            HDEVINFO           DeviceInfoSet,
  [in, out]       PSP_DEVINFO_DATA   DeviceInfoData,
  [in]            DWORD              Flags,
  [in, optional]  PSP_DETSIG_CMPPROC CompareProc,
  [in, optional]  PVOID              CompareContext,
  [out, optional] PSP_DEVINFO_DATA   DupDeviceInfoData
);

Parameter

[in] DeviceInfoSet

Ein Handle für einen Geräteinformationssatz , der ein Geräteinformationselement enthält, das das zu registrierende Gerät darstellt. Der Geräteinformationssatz darf keine Remoteelemente enthalten.

[in, out] DeviceInfoData

Ein Zeiger auf eine SP_DEVINFO_DATA-Struktur , die das 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.

[in] Flags

Ein Flagwert, der steuert, wie das Gerät registriert wird, der null oder der folgende Wert sein kann:

SPRDI_FIND_DUPS

Suchen Sie nach einem zuvor vorhandenen Gerät instance, das dem Gerät entspricht, das von DeviceInfoData dargestellt wird. Wenn dieses Flag nicht angegeben wird, wird das Gerät instance registriert, unabhängig davon, ob ein Gerät instance bereits dafür vorhanden ist.

Wenn der Aufrufer CompareProc bereitstellt, muss der Aufrufer auch dieses Flag festlegen.

[in, optional] CompareProc

Ein Zeiger auf eine Vergleichsrückruffunktion, die bei der Duplikaterkennung verwendet werden soll. Dieser Parameter ist optional und kann NULL sein. Wenn dieser Parameter angegeben wird, wird die Rückruffunktion für jedes Gerät aufgerufen, instance das dieselbe Klasse wie das gerät instance aufweist, das registriert wird. Der Prototyp der Rückruffunktion lautet wie folgt:

typedef  DWORD (CALLBACK* PSP_DETSIG_CMPPROC) (
    IN HDEVINFO  DeviceInfoSet,
    IN PSP_DEVINFO_DATA  NewDeviceData,
    IN PSP_DEVINFO_DATA  ExistingDeviceData,
    IN PVOID  CompareContextOPTIONAL
    );

Die Compare-Funktion muss ERROR_DUPLICATE_FOUND zurückgeben, wenn sie feststellt, dass es sich bei den beiden Geräten um Duplikate handelt. Andernfalls sollte NO_ERROR zurückgegeben werden. Wenn ein anderer Fehler auftritt, sollte die Rückruffunktion den entsprechenden ERROR_*-Code zurückgeben, um den Fehler anzuzeigen.

Wenn CompareProc nicht angegeben ist und die Duplizierungserkennung angefordert wird, wird ein Standardvergleichsverhalten verwendet. Standardmäßig wird die Erkennungssignatur des neuen Geräts mit der Erkennungssignatur aller anderen Geräte in der Klasse verglichen. Die Erkennungssignatur ist im klassenspezifischen Ressourcendeskriptor der Startprotokollkonfiguration des Geräts enthalten.

[in, optional] CompareContext

Ein Zeiger auf einen vom Aufrufer bereitgestellten Kontextpuffer, der an die Rückruffunktion übergeben wird. Dieser Parameter wird ignoriert, wenn CompareProc nicht angegeben ist.

[out, optional] DupDeviceInfoData

Ein Zeiger auf eine SP_DEVINFO_DATA Struktur zum Empfangen von Informationen zu einem doppelten Gerät, instance, falls vorhanden, durch den Versuch, dieses Gerät zu registrieren, ermittelt wurde. Dieser Parameter ist optional und kann NULL sein. Wenn dieser Parameter angegeben ist, muss der Aufrufer DupDeviceInfoData festlegen.cbSize auf sizeof(SP_DEVINFO_DATA). Dies wird ausgefüllt, wenn die Funktion FALSE zurückgibt und GetLastError ERROR_DUPLICATE_FOUND zurückgibt. Dieses Geräteinformationselement wird als Mitglied des angegebenen DeviceInfoSet hinzugefügt, sofern es nicht bereits ein Member ist. Wenn DupDeviceInfoData nicht angegeben ist, wird das Duplikat dem Geräteinformationssatz nicht hinzugefügt.

Wenn Sie diese Funktion beim Behandeln einer DIF_REGISTERDEVICE-Anforderung aufrufen, muss der DupDeviceInfoData-ParameterNULL sein.

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

SetupDiRegisterDeviceInfo ist in erster Linie für die Registrierung eines Nicht-PnP-Geräts beim PnP-Manager (Plug & Play) auf einem lokalen Computer konzipiert. Obwohl SetupDiRegisterDeviceInfo nicht fehlschlägt, wenn der Geräteinformationssatz für einen Remotecomputer festgelegt ist, ist das Ergebnis nur eingeschränkt nutzbar, da der Geräteinformationssatz anschließend nicht mit DIF_Xxx-Installationsanforderungen oder SetupDi Xxx-Funktionen verwendet werden kann, die keine Vorgänge auf einem Remotecomputer unterstützen. Das Aufrufen von SetupDiCreateDevRegKey zum Ausführen eines INF-Abschnitts für ein neu registriertes Gerät auf einem Remotecomputer schlägt beispielsweise fehl.

Hinweis Nur ein Klasseninstallationsprogramm sollte SetupDiRegisterDeviceInfo aufrufen, und das nur in den Situationen, in denen das Klasseninstallationsprogramm Geräteregistrierungsvorgänge ausführen muss, nachdem SetupDiRegisterDeviceInfo den Standardvorgang für die Geräteregistrierung abgeschlossen hat. In solchen Situationen muss das Klasseninstallationsprogramm SetupDiRegisterDeviceInfo direkt aufrufen, wenn das Installationsprogramm eine DIF_REGISTERDEVICE Anforderung verarbeitet. Weitere Informationen zum Aufrufen des Standardhandlers finden Sie unter Aufrufen von DIF-Standardcodehandlern.
 
Nach der Registrierung eines Geräteinformationselements sollte der Aufrufer alle gespeicherten Kopien des Diesem Gerät zugeordneten DevInst-Handle aktualisieren. Dies ist erforderlich, da sich der Handle-Wert während der Registrierung möglicherweise geändert hat. Der Aufrufer muss die SP_DEVINFO_DATA Struktur nicht erneut abrufen, da das DevInst-Feld der Struktur aktualisiert wird, um den aktuellen Wert des Handles widerzuspiegeln.

Rufen Sie diese Funktion nicht direkt für PnP-Geräteinstanzen auf. PnP-Geräteinstanzen werden automatisch vom Betriebssystem registriert. Sie müssen jedoch Nicht-PnP-Geräteinstanzen auf eine der folgenden Arten registrieren:

  1. Wenn Ihre Installationsanwendung eine DIF_DETECT Anforderung verwendet, um ein Gerät erfolgreich zu erkennen, sollte sie auch eine DIF_REGISTERDEVICE Anforderung verwenden, um das Gerät instance zu registrieren. Die Anforderung sollte standardmäßig behandelt werden. (Standardmäßig ruft SetupDiCallClassInstaller zuerst den Klasseninstallationsprogramm und die Klassen-Co-Installer auf, um die Duplikaterkennung durchzuführen und das Gerät instance zu registrieren. Wenn diese Installationsprogramme das Gerät nicht instance registrieren, ruft SetupDiCallClassInstallerSetupDiRegisterDeviceInfo auf, um die Duplikaterkennung durchzuführen und das Gerät instance zu registrieren.)
  2. Wenn Ihre Installationsanwendung ein Gerät instance erstellt (z. B. durch Aufrufen von SetupDiCreateDeviceInfo), aber keine Duplikaterkennung durchführt, sollte Ihre Installationsanwendung eine DIF_REGISTERDEVICE-Anforderung verwenden, um das Gerät instance zu registrieren. Die Anforderung sollte wie zuvor beschrieben standardmäßig behandelt werden.
  3. Wenn Ihre Installationsanwendung ein neues Gerät erstellt und eine Duplikaterkennung durchführt, sollte Ihre Installationsanwendung eine DIF_REGISTERDEVICE-Anforderung verwenden, aber setupDiCallClassInstaller daran hindern , SetupDiRegisterDeviceInfo aufzurufen. Um zu verhindern, dass SetupDiCallClassInstallerSetupDiRegisterDeviceInfo aufruft, legen Sie das DI_NODI_DEFAULTACTION-Flag im Flags-Element der SP_DEVINSTALL_PARAMS-Struktur für das gerät instance fest.

    Wenn SetupDiCallClassInstallertrue für die DIF_REGISTERDEVICE Anforderung zurückgibt, registriert der Klasseninstallationsprogramm oder die Klassen-Co-Installer das Gerät instance. In diesem Fall kann die Installationsanwendung das Gerät weiterhin installieren.

    Wenn SetupDiCallClassInstallerfalse für die DIF_REGISTERDEVICE Anforderung zurückgibt, hat der Klasseninstallationsprogramm oder die Klassen-Co-Installer das Gerät instance nicht registriert. In diesem Fall sollte die Installationsanwendung je nach dem letzten Fehler, den GetLastError für die Anforderung zurückgibt, eine der folgenden Aktionen ausführen:

    • Wenn der letzte Fehler ERROR_DI_DO_DEFAULT ist, kann die Installationsanwendung SetupDiRegisterDeviceInfo direkt aufrufen und eine CompareProc-Instanz zur Duplikaterkennung bereitstellen. Wenn dieser Aufruf erfolgreich ist und keine Duplikate gefunden werden, kann die Geräteinstallation fortgesetzt werden. Wenn ein Duplikat gefunden wird, gibt SetupDiRegisterDeviceInfoFALSE zurück, und die Installationsanwendung muss die Geräteinstallation beenden.
    • Wenn der letzte Fehler nicht ERROR_DI_DO_DEFAULT ist, muss die Installationsanwendung die Geräteinstallation beenden.
    Der Aufrufer von SetupDiRegisterDeviceInfo 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 (einschließlich Setupapi.h)
Bibliothek Setupapi.lib
DLL Setupapi.dll

Weitere Informationen

DIF_REGISTERDEVICE

SP_DEVINFO_DATA

SP_DEVINSTALL_PARAMS