RegCreateKeyExA-Funktion (winreg.h)

Artikel
08/27/2023

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.

Rufen Sie die RegCreateKeyTransacted-Funktion auf, um transaktionsierte Registrierungsvorgänge für einen Schlüssel auszuführen.

Anwendungen, die den Systemzustand sichern oder wiederherstellen, einschließlich Systemdateien und Registrierungsstrukturen, sollten anstelle der Registrierungsfunktionen den Volumeschattenkopiedienst verwenden.

Syntax

LSTATUS RegCreateKeyExA(
  [in]            HKEY                        hKey,
  [in]            LPCSTR                      lpSubKey,
                  DWORD                       Reserved,
  [in, optional]  LPSTR                       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 über KEY_CREATE_SUB_KEY Zugriff auf den Schlüssel verfügen. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für Registrierungsschlüssel.

Der Zugriff für die Schlüsselerstellung wird anhand des Sicherheitsdeskriptors des Registrierungsschlüssels überprüft, nicht mit der Zugriffsmaske, die beim Abrufen des Handles angegeben wurde. Selbst wenn hKey mit einem samDesired von KEY_READ geöffnet wurde, kann er daher in Vorgängen verwendet werden, die die Registrierung ändern, sofern dies durch den Sicherheitsdeskriptor 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 Schlüssels sein, der durch den hKey-Parameter identifiziert wird. 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
REG_OPTION_BACKUP_RESTORE 0x00000004L	Wenn dieses Flag festgelegt ist, ignoriert die Funktion den parameter samDesired 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 den Zugriffsrechten KEY_READ 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, DELETE 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.
REG_OPTION_CREATE_LINK 0x00000002L	Hinweis Symbolische Registrierungslinks sollten aus Gründen der Anwendungskompatibilität nur verwendet werden, wenn dies unbedingt erforderlich ist. Dieser Schlüssel ist eine symbolische Verknüpfung. Der Zielpfad wird dem L"SymbolicLinkValue"-Wert des Schlüssels zugewiesen. Der Zielpfad muss ein absoluter Registrierungspfad sein.
REG_OPTION_NON_VOLATILE 0x00000000L	Dieser Schlüssel ist nicht flüchtig. Dies ist die Standardeinstellung. Die Informationen werden in einer Datei gespeichert und beim Neustart des Systems beibehalten. Die RegSaveKey-Funktion speichert Schlüssel, die nicht flüchtig sind.
REG_OPTION_VOLATILE 0x00000001L	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 schlüssel ignoriert, die bereits vorhanden sind. 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.

Der lpSecurityDescriptor-Member der -Struktur gibt einen Sicherheitsdeskriptor für den neuen Schlüssel an. Wenn lpSecurityAttributesNULL ist, ruft der Schlüssel einen Standardsicherheitsdeskriptor ab. 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 keiner der vordefinierten Registrierungsschlüssel ist, rufen Sie die RegCloseKey-Funktion auf, nachdem Sie das Handle verwendet haben.

[out, optional] lpdwDisposition

Ein Zeiger auf eine Variable, die einen der folgenden Dispositionswerte empfängt.

Wert	Bedeutung
REG_CREATED_NEW_KEY 0x00000001L	Der Schlüssel war nicht vorhanden und wurde erstellt.
REG_OPENED_EXISTING_KEY 0x00000002L	Der Schlüssel war vorhanden und wurde einfach geöffnet, ohne geändert zu werden.

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 in Winerror.h definierter Fehlercode ungleich null. 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 vier Ebenen tief zur gleichen Zeit wie die drei vorherigen Unterschlüssel erstellen, 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-Strukturen 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 Registrierungsvirtualisierung und 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