RegCreateKeyA-Funktion (winreg.h)

Artikel
11/20/2024

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 zur Kompatibilität mit 16-Bit-Versionen von Windows bereitgestellt. Anwendungen sollten die RegCreateKeyEx--Funktion verwenden. Anwendungen, die den Systemstatus sichern oder wiederherstellen, einschließlich Systemdateien und Registrierungsstruktur, sollten jedoch den Volume Shadow Copy Service anstelle der Registrierungsfunktionen verwenden.

Syntax

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

Parameter

[in] hKey

Ein Handle zu einem geöffneten Registrierungsschlüssel. Der Aufrufvorgang muss über KEY_CREATE_SUB_KEY Zugriff auf den Schlüssel verfügen. Weitere Informationen finden Sie unter Registry Key Security and Access Rights.

Der Zugriff auf die Schlüsselerstellung wird mit dem Sicherheitsdeskriptor 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 in Vorgängen verwendet werden, die Schlüssel erstellen, wenn 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:

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

Wenn hKey- einer der vordefinierten Schlüssel ist, kann lpSubKey-NULL-sein. In diesem Fall empfängt phkResult das gleiche 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 nicht einer der vordefinierten Registrierungsschlüssel ist, rufen Sie die RegCloseKey--Funktion auf, nachdem Sie die Verwendung des Handle abgeschlossen haben.

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 FORMAT_MESSAGE_FROM_SYSTEM Flag verwenden, um eine allgemeine Beschreibung des Fehlers zu erhalten.

Bemerkungen

Eine Anwendung kann keinen Schlüssel erstellen, der ein direktes untergeordnetes Element von HKEY_USERS oder HKEY_LOCAL_MACHINEist. Eine Anwendung kann Unterschlüssel in niedrigeren Ebenen der HKEY_USERS oder HKEY_LOCAL_MACHINE Strukturen erstellen.

Wenn Ihr Dienst oder Ihre Anwendung unterschiedliche Benutzer imitiert, 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. Eine Anwendung kann z. B. einen Unterschlüssel mit vier Ebenen gleichzeitig mit den drei vorhergehenden Unterschlüsseln erstellen, indem eine Zeichenfolge des folgenden Formulars für den parameter lpSubKey angegeben wird:

unterschlüssel1\subkey2\subkey3\subkey4

Beachten Sie, dass dieses Verhalten dazu führt, dass unerwünschte Schlüssel erstellt werden, wenn ein vorhandener Schlüssel im Pfad falsch geschrieben ist.

Anmerkung

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
mindestens unterstützte Client-	Windows 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winreg.h (enthalten Windows.h)
Library	Advapi32.lib
DLL-	Advapi32.dll