SetupDiCreateDevRegKeyW-Funktion (setupapi.h)

Artikel
08/26/2023

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 SetupDiCreateDevRegKeyW(
  [in]           HDEVINFO         DeviceInfoSet,
  [in]           PSP_DEVINFO_DATA DeviceInfoData,
  [in]           DWORD            Scope,
  [in]           DWORD            HwProfile,
  [in]           DWORD            KeyType,
  [in, optional] HINF             InfHandle,
  [in, optional] PCWSTR           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 sind nicht spezifisch für ein bestimmtes Hardwareprofil. Auf NT-basierten Betriebssystemen wird dadurch ein Schlüssel erstellt, der bei HKEY_LOCAL_MACHINE gerootet ist. 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 wird in einem der Hardwareprofil-spezifischen Branches gerootet, anstatt 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 0 ist, 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 abzurufen.

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 für 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. Für frühere Windows-Versionen hat dieses Handle 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 Eintrag LayoutFile im Abschnitt in einer INF-Version), muss die Layoutdatei durch einen Aufruf von SetupOpenAppendInfFile (in der Microsoft Windows SDK-Dokumentation beschrieben) 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 werden, 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 automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante 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
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