RegCreateKeyExW-Funktion (winreg.h)
Erstellt den angegebenen Registrierungsschlüssel. Wenn der Schlüssel bereits vorhanden ist, wird er von der Funktion geöffnet. Beachten Sie, dass bei Schlüsselnamen die Groß-/Kleinschreibung nicht beachtet wird.
Um Transaktionsregistrierungsvorgänge für einen Schlüssel auszuführen, rufen Sie die RegCreateKeyTransacted-Funktion auf.
Anwendungen, die den Systemstatus sichern oder wiederherstellen, einschließlich Systemdateien und Registrierungsstrukturen, sollten anstelle der Registrierungsfunktionen den Volume Shadow Copy Service verwenden.
Syntax
LSTATUS RegCreateKeyExW(
[in] HKEY hKey,
[in] LPCWSTR lpSubKey,
DWORD Reserved,
[in, optional] LPWSTR lpClass,
[in] DWORD dwOptions,
[in] REGSAM samDesired,
[in, optional] const LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[out] PHKEY phkResult,
[out, optional] LPDWORD lpdwDisposition
);
Parameter
[in] hKey
Ein Handle für einen geöffneten Registrierungsschlüssel. Der aufrufende Prozess muss KEY_CREATE_SUB_KEY Zugriff auf den Schlüssel haben. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für Registrierungsschlüssel.
Der Zugriff für die Schlüsselerstellung wird anhand der Sicherheitsbeschreibung des Registrierungsschlüssels überprüft, nicht mit der Zugriffsmaske, die beim Abrufen des Handles angegeben wurde. Daher kann hKey auch wenn mit einem samDesired von KEY_READ geöffnet wurde, in Vorgängen verwendet werden, die die Registrierung ändern, sofern dies durch die Sicherheitsbeschreibung zulässig ist.
Dieses Handle wird von der RegCreateKeyEx - oder RegOpenKeyEx-Funktion zurückgegeben, oder es kann sich um einen der folgenden vordefinierten Schlüssel handelt:
- HKEY_CLASSES_ROOT
- HKEY_CURRENT_CONFIG
- HKEY_CURRENT_USER
- HKEY_LOCAL_MACHINE
- HKEY_USERS
[in] lpSubKey
Der Name eines Unterschlüssels, den diese Funktion öffnet oder erstellt. Der angegebene Unterschlüssel muss ein Unterschlüssel des durch den hKey-Parameter identifizierten Schlüssels sein. Es kann bis zu 32 Ebenen tief in der Registrierungsstruktur sein. Weitere Informationen zu Schlüsselnamen finden Sie unter Struktur der Registrierung.
Wenn lpSubKey ein Zeiger auf eine leere Zeichenfolge ist, empfängt phkResult ein neues Handle für den durch hKey angegebenen Schlüssel.
Dieser Parameter darf nicht NULL sein.
Reserved
Dieser Parameter ist reserviert und muss null sein.
[in, optional] lpClass
Der benutzerdefinierte Klassentyp dieses Schlüssels. Dieser Parameter kann ignoriert werden. Dieser Parameter kann NULL sein.
[in] dwOptions
Dieser Parameter kann einen der folgenden Werte annehmen.
| Wert | Bedeutung |
|---|---|
|
Wenn dieses Flag festgelegt ist, ignoriert die Funktion den samDesired-Parameter und versucht, den Schlüssel mit dem Zugriff zu öffnen, der zum Sichern oder Wiederherstellen des Schlüssels erforderlich ist. Wenn für den aufrufenden Thread die Berechtigung SE_BACKUP_NAME aktiviert ist, wird der Schlüssel mit dem ACCESS_SYSTEM_SECURITY und KEY_READ Zugriffsrechten geöffnet. Wenn für den aufrufenden Thread die Berechtigung SE_RESTORE_NAME aktiviert ist, wird der Schlüssel ab Windows Vista mit den Zugriffsrechten ACCESS_SYSTEM_SECURITY, LÖSCHEN und KEY_WRITE geöffnet. Wenn beide Berechtigungen aktiviert sind, verfügt der Schlüssel über die kombinierten Zugriffsrechte für beide Berechtigungen. Weitere Informationen finden Sie unter Ausführen mit speziellen Berechtigungen. |
|
Hinweis Symbolische Registrierungslinks sollten nur zur Anwendungskompatibilität verwendet werden, wenn dies unbedingt erforderlich ist.
|
|
Dieser Schlüssel ist nicht volatil. Dies ist der Standardwert. Die Informationen werden in einer Datei gespeichert und beim Neustart des Systems beibehalten. Die RegSaveKey-Funktion speichert Schlüssel, die nicht volatil sind. |
|
Alle von der Funktion erstellten Schlüssel sind flüchtig. Die Informationen werden im Arbeitsspeicher gespeichert und nicht beibehalten, wenn der entsprechende Registrierungshive entladen wird. Bei HKEY_LOCAL_MACHINE tritt dies nur auf, wenn das System ein vollständiges Herunterfahren initiiert. Bei Registrierungsschlüsseln, die von der RegLoadKey-Funktion geladen werden, tritt dies auf, wenn der entsprechende RegUnLoadKey ausgeführt wird. Die RegSaveKey-Funktion speichert keine flüchtigen Schlüssel. Dieses Flag wird für bereits vorhandene Schlüssel ignoriert.
Hinweis Wenn ein Benutzer das Herunterfahren ausgewählt hat, ist ein schnelles Herunterfahren das Standardverhalten für das System.
|
[in] samDesired
Eine Maske, die die Zugriffsrechte für den zu erstellenden Schlüssel angibt. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für Registrierungsschlüssel.
[in, optional] lpSecurityAttributes
Ein Zeiger auf eine SECURITY_ATTRIBUTES-Struktur , die bestimmt, ob das zurückgegebene Handle von untergeordneten Prozessen geerbt werden kann. Wenn lpSecurityAttributesNULL ist, kann das Handle nicht geerbt werden.
Das lpSecurityDescriptor-Element der Struktur gibt einen Sicherheitsdeskriptor für den neuen Schlüssel an. Wenn lpSecurityAttributesNULL ist, erhält der Schlüssel eine Standardsicherheitsbeschreibung. Die ACLs in einem Standardsicherheitsdeskriptor für einen Schlüssel werden von seinem direkten übergeordneten Schlüssel geerbt.
[out] phkResult
Ein Zeiger auf eine Variable, die ein Handle für den geöffneten oder erstellten Schlüssel empfängt. Wenn der Schlüssel nicht einer der vordefinierten Registrierungsschlüssel ist, rufen Sie die RegCloseKey-Funktion auf, nachdem Sie die Verwendung des Handle abgeschlossen haben.
[out, optional] lpdwDisposition
Ein Zeiger auf eine Variable, die einen der folgenden Dispositionswerte empfängt.
Wenn lpdwDispositionNULL ist, werden keine Dispositionsinformationen zurückgegeben.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.
Wenn die Funktion fehlschlägt, ist der Rückgabewert ein nichtzero-Fehlercode, der in Winerror.h definiert ist. Sie können die FormatMessage-Funktion mit dem flag FORMAT_MESSAGE_FROM_SYSTEM verwenden, um eine generische Beschreibung des Fehlers abzurufen.
Hinweise
Der Schlüssel, den die RegCreateKeyEx-Funktion erstellt, weist keine Werte auf. Eine Anwendung kann die RegSetValueEx-Funktion verwenden, um Schlüsselwerte festzulegen.
Die RegCreateKeyEx-Funktion erstellt alle fehlenden Schlüssel im angegebenen Pfad. Eine Anwendung kann dieses Verhalten nutzen, um mehrere Schlüssel gleichzeitig zu erstellen. Beispielsweise kann eine Anwendung einen Unterschlüssel erstellen, der vier Ebenen tief zur gleichen Zeit wie die drei vorherigen Unterschlüssel enthält, indem sie eine Zeichenfolge der folgenden Form für den lpSubKey-Parameter angibt:
subkey1\subkey2\subkey3\subkey4
Beachten Sie, dass dieses Verhalten zur Erstellung unerwünschter Schlüssel führt, wenn ein vorhandener Schlüssel im Pfad falsch geschrieben ist.
Eine Anwendung kann keinen Schlüssel erstellen, der ein direktes untergeordnetes Element von HKEY_USERS oder HKEY_LOCAL_MACHINE ist. Eine Anwendung kann Unterschlüssel in niedrigeren Ebenen der HKEY_USERS - oder HKEY_LOCAL_MACHINE-Struktur erstellen.
Wenn Ihr Dienst oder Ihre Anwendung die Identität verschiedener Benutzer angibt, verwenden Sie diese Funktion nicht mit HKEY_CURRENT_USER. Rufen Sie stattdessen die RegOpenCurrentUser-Funktion auf.
Beachten Sie, dass Vorgänge, die auf bestimmte Registrierungsschlüssel zugreifen, umgeleitet werden. Weitere Informationen finden Sie unter Registrierungsvirtualisierungund 32-Bit- und 64-Bit-Anwendungsdaten in der Registrierung.
Hinweis
Der winreg.h-Header definiert RegCreateKeyEx 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) | Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winreg.h (einschließlich Windows.h) |
| Bibliothek | Advapi32.lib |
| DLL | Advapi32.dll |