RegCreateKeyExA-Funktion (winreg.h)

Erstellt den angegebenen Registrierungsschlüssel. Wenn der Schlüssel bereits vorhanden ist, öffnet sie die Funktion. Beachten Sie, dass bei Schlüsselnamen die Groß-/Kleinschreibung nicht beachtet wird.

Rufen Sie die RegCreateKeyTransacted-Funktion auf, um Transaktionen für einen Schlüssel auszuführen.

Anwendungen, die den Systemstatus sichern oder wiederherstellen, einschließlich Systemdateien und Registrierungsstruktur, sollten den Volume Shadow Copy Service anstelle der Registrierungsfunktionen 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 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 die Registrierung ändern, wenn sie von der Sicherheitsbeschreibung zugelassen werden.

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

Wenn lpSubKey ein Zeiger auf eine leere Zeichenfolge ist, empfängt phkResult einen neuen Handle für den durch hKeyangegebenen Schlüssel.

Dieser Parameter kann nicht NULL-werden.

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 einer der folgenden Werte sein:

[in] samDesired

Eine Maske, die die Zugriffsrechte für den zu erstellenden Schlüssel angibt. Weitere Informationen finden Sie unter Registry Key Security and Access Rights.

[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 Mitglied der Struktur gibt einen Sicherheitsdeskriptor für den neuen Schlüssel an. Wenn lpSecurityAttributesNULL-ist, erhält der Schlüssel einen Standardsicherheitsdeskriptor. 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 Löschungsinformationen 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 FORMAT_MESSAGE_FROM_SYSTEM Flag verwenden, um eine allgemeine Beschreibung des Fehlers zu erhalten.

Bemerkungen

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

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.

Beachten Sie, dass Vorgänge, die auf bestimmte Registrierungsschlüssel zugreifen, umgeleitet werden. Weitere Informationen finden Sie unter Registry Virtualization und 32-Bit- und 64-Bit-Anwendungsdaten in der Registrierung.

Anforderungen

Siehe auch

RegCloseKey-

RegDeleteKey-

RegOpenKeyEx-

RegSaveKey-

Registrierungsfunktionen

Registrierungsübersicht

SECURITY_ATTRIBUTES