SetupDiCreateDevRegKeyA-Funktion (setupapi.h)
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 |