RegCreateKeyA-Funktion (winreg.h)

Artikel
08/27/2023

Erstellt den angegebenen Registrierungsschlüssel. Wenn der Schlüssel bereits in der Registrierung vorhanden ist, wird er von der Funktion geöffnet.

Hinweis Diese Funktion wird nur aus Gründen der Kompatibilität mit 16-Bit-Versionen von Windows bereitgestellt. Anwendungen sollten die RegCreateKeyEx-Funktion verwenden. Anwendungen, die den Systemzustand sichern oder wiederherstellen, einschließlich Systemdateien und Registrierungsstrukturen, sollten jedoch den Volumeschattenkopiedienst anstelle der Registrierungsfunktionen verwenden.

Syntax

LSTATUS RegCreateKeyA(
  [in]           HKEY   hKey,
  [in, optional] LPCSTR lpSubKey,
  [out]          PHKEY  phkResult
);

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 es daher in Vorgängen verwendet werden, die Schlüssel erstellen, 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, optional] lpSubKey

Der Name eines Schlüssels, den diese Funktion öffnet oder erstellt. Dieser Schlüssel muss ein Unterschlüssel des Schlüssels sein, der durch den hKey-Parameter identifiziert wird.

Weitere Informationen zu Schlüsselnamen finden Sie unter Struktur der Registrierung.

Wenn hKey einer der vordefinierten Schlüssel ist, kann lpSubKeyNULL sein. In diesem Fall erhält phkResult dasselbe hKey-Handle , das an die Funktion übergeben wird.

[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.

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

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.

Die RegCreateKey-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.

Hinweis

Der winreg.h-Header definiert RegCreateKey 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)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winreg.h (Windows.h einschließen)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll