SetupDiCreateDevRegKeyA-Funktion (setupapi.h)

Artikel
03/01/2024

Die SetupDiCreateDevRegKey-Funktion erstellt einen Registrierungsschlüssel für gerätespezifische Konfigurationsinformationen und gibt ein Handle an den Schlüssel zurück.

Syntax

WINSETUPAPI HKEY SetupDiCreateDevRegKeyA(
  [in]           HDEVINFO         DeviceInfoSet,
  [in]           PSP_DEVINFO_DATA DeviceInfoData,
  [in]           DWORD            Scope,
  [in]           DWORD            HwProfile,
  [in]           DWORD            KeyType,
  [in, optional] HINF             InfHandle,
  [in, optional] PCSTR            InfSectionName
);

Parameter

[in] DeviceInfoSet

Ein Handle für einen Geräteinformationssatz , der ein Geräteinformationselement enthält, das das Gerät darstellt, für das ein Registrierungsschlüssel erstellt werden soll.

[in] DeviceInfoData

Ein Zeiger auf eine SP_DEVINFO_DATA-Struktur , die das Geräteinformationselement in DeviceInfoSet angibt.

[in] Scope

Der Bereich des zu erstellenden Registrierungsschlüssels. Der Bereich bestimmt, wo die Informationen gespeichert werden. Der erstellte Schlüssel kann global oder hardwareprofilspezifisch sein. Folgenden Werte sind möglich:

DICS_FLAG_GLOBAL

Erstellen Sie einen Schlüssel zum Speichern globaler Konfigurationsinformationen. Diese Informationen beziehen sich nicht auf ein bestimmtes Hardwareprofil. Auf NT-basierten Betriebssystemen wird dadurch ein Schlüssel erstellt, der auf HKEY_LOCAL_MACHINE basiert. Der genaue geöffnete Schlüssel hängt vom Wert des KeyType-Parameters ab.

DICS_FLAG_CONFIGSPECIFIC

Erstellen Sie einen Schlüssel zum Speichern hardwareprofilspezifischer Konfigurationsinformationen. Dieser Schlüssel basiert auf einem der hardwareprofilspezifischen Branches und nicht auf HKEY_LOCAL_MACHINE.

[in] HwProfile

Das Hardwareprofil, für das ein Schlüssel erstellt werden soll, wenn HwProfileFlags auf SPDICS_FLAG_CONFIGSPECIFIC festgelegt ist. Wenn HwProfile den Wert 0 aufweist, wird der Schlüssel für das aktuelle Hardwareprofil erstellt. Wenn HwProfileFlags SPDICS_FLAG_GLOBAL ist, wird HwProfile ignoriert.

[in] KeyType

Der Typ des zu erstellenden Registrierungsspeicherschlüssels. Folgenden Werte sind möglich:

DIREG_DEV

Erstellen Sie einen Hardwareschlüssel für das Gerät.

DIREG_DRV

Erstellen Sie einen Softwareschlüssel für das Gerät.

[in, optional] InfHandle

Das Handle für eine geöffnete INF-Datei, die einen INF DDInstall-Abschnitt enthält, der für den neu erstellten Schlüssel ausgeführt werden soll. Dieser Parameter ist optional und kann NULL sein. Wenn dieser Parameter angegeben ist, muss auch InfSectionName angegeben werden.

[in, optional] InfSectionName

Der Name eines INF DDInstall-Abschnitts in der von InfHandle angegebenen INF-Datei. Dieser Abschnitt wird für den neu erstellten Schlüssel ausgeführt. Dieser Parameter ist optional und kann NULL sein. Wenn dieser Parameter angegeben ist, muss auch InfHandle angegeben werden.

Rückgabewert

Wenn SetupDiCreateDevRegKey erfolgreich ist, gibt die Funktion ein Handle an den angegebenen Registrierungsschlüssel zurück, in dem gerätespezifische Konfigurationsdaten gespeichert und abgerufen werden können. Wenn SetupDiCreateDevRegKey fehlschlägt, gibt die Funktion INVALID_HANDLE_VALUE zurück. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.

Hinweise

Der Aufrufer von SetupDiCreateDevRegKey muss Mitglied der Gruppe Administratoren sein.

Schließen Sie das von SetupDiCreateDevRegKey zurückgegebene Handle, indem Sie RegCloseKey aufrufen.

Wenn der angegebene Schlüssel bereits vorhanden ist, gibt SetupDiCreateDevRegKey ein Handle für diesen Schlüssel zurück. Andernfalls erstellt SetupDiCreateDevRegKey den angegebenen Schlüssel und gibt ein Handle an den neuen Schlüssel zurück. Für Windows Server 2003 und höhere Versionen von Windows verfügt das Schlüsselhandle nur über KEY_READ und KEY_WRITE Zugriff. Bei früheren Windows-Versionen verfügt dieses Handle über KEY_ALL_ACCESS Zugriff.

Das angegebene Gerät instance muss registriert werden, bevor SetupDiCreateDevRegKey aufgerufen wird. Beachten Sie jedoch, dass das Betriebssystem PnP-Geräteinstanzen automatisch registriert. Informationen zum Registrieren von Nicht-PnP-Geräteinstanzen finden Sie unter SetupDiRegisterDeviceInfo.

Bei Installationen, die Layoutdateien verwenden (angegeben durch den LayoutFile-Eintrag in einem INF-Versionsabschnitt), muss die Layoutdatei durch einen Aufruf von SetupOpenAppendInfFile (beschrieben in der Microsoft Windows SDK-Dokumentation) geöffnet werden, bevor SetupDiCreateDevRegKey aufgerufen wird.

Wenn der angegebene Geräteinformationssatz Geräteinformationselemente für ein Remotesystem enthält und auch InfHandle und InfSectionName angegeben sind, schlägt die Erstellungsanforderung fehl, und ein späterer Aufruf von GetLastError gibt ERROR_REMOTE_REQUEST_UNSUPPORTED zurück.

Hinweis

Der Setupapi.h-Header definiert SetupDiCreateDevRegKey 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 Code, der nicht Codierungsneutral ist, 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
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