SetupDiCreateDevRegKeyA-Funktion (setupapi.h)
Die SetupDiCreateDevRegKey--Funktion erstellt einen Registrierungsschlüssel für gerätespezifische Konfigurationsinformationen und gibt einen 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 zu einem Geräteinformationssatz, das 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 hardwarespezifisch sein. Dies kann einer der folgenden Werte sein:
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_MACHINEverwurzelt 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 von hardwareprofilspezifischen Konfigurationsinformationen. Dieser Schlüssel ist in einer der hardwareprofilspezifischen Verzweigungen und nicht in HKEY_LOCAL_MACHINEverwurzelt.
[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. Dies kann einer der folgenden Werte sein:
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, für den neu erstellten Schlüssel ausgeführt werden soll. Dieser Parameter ist optional und kann NULL-werden. Wenn dieser Parameter angegeben ist, muss auch InfSectionName- angegeben werden.
[in, optional] InfSectionName
Der Name eines INF-DDInstall- Abschnitts in der INF-Datei, die durch InfHandle-angegeben wird. Dieser Abschnitt wird für den neu erstellten Schlüssel ausgeführt. Dieser Parameter ist optional und kann NULL-werden. 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.
Bemerkungen
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 an 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. Für frühere Windows-Versionen hat dieses Handle KEY_ALL_ACCESS Zugriff.
Die angegebene Geräteinstanz 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.
Für Installationen, die Layoutdateien verwenden (angegeben durch den Eintrag LayoutFile in einem Abschnitt 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 InfHandle- und InfSectionName- ebenfalls angegeben werden, schlägt die Erstellungsanforderung fehl, und ein anschließender Aufruf von GetLastError gibt ERROR_REMOTE_REQUEST_UNSUPPORTED zurück.
Anmerkung
Der header setupapi.h 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 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 |
|---|---|
| mindestens unterstützte Client- | Verfügbar in Microsoft Windows 2000 und höheren Versionen von Windows. |
| Zielplattform- | Desktop |
| Header- | setupapi.h (include Setupapi.h) |
| Library | Setupapi.lib |