RegCreateKeyTransactedA-Funktion (winreg.h)

Artikel
08/27/2023

Erstellt den angegebenen Registrierungsschlüssel und ordnet ihn einer Transaktion zu. 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.

Anwendungen, die den Systemstatus sichern oder wiederherstellen, einschließlich Systemdateien und Registrierungsstrukturen, sollten anstelle der Registrierungsfunktionen den Volume Shadow Copy Service verwenden.

Syntax

LSTATUS RegCreateKeyTransactedA(
  [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,
  [in]            HANDLE                      hTransaction,
                  PVOID                       pExtendedParemeter
);

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. Selbst wenn hKey mit einem samDesired von KEY_READ geöffnet wurde, kann es in Vorgängen verwendet werden, die Schlüssel erstellen, sofern dies durch die Sicherheitsbeschreibung zulässig ist.

Dieses Handle wird von der RegCreateKeyTransacted - oder RegOpenKeyTransacted-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

Die benutzerdefinierte Klasse 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 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 mit dem ACCESS_SYSTEM_SECURITY und KEY_WRITE Zugriffsrechten 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_NON_VOLATILE 0x00000000L	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.
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 auf, wenn das System heruntergefahren wird. 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.

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

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.

[in] hTransaction

Ein Handle für eine aktive Transaktion. Dieses Handle wird von der CreateTransaction-Funktion zurückgegeben.

pExtendedParemeter

Dieser Parameter ist reserviert und muss NULL sein.

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

Wenn ein Schlüssel mit dieser Funktion erstellt wird, werden nachfolgende Vorgänge für den Schlüssel ausgeführt. Wenn ein nicht transaktionierter Vorgang für den Schlüssel ausgeführt wird, bevor die Transaktion committet wird, wird ein Rollback für die Transaktion ausgeführt. Nachdem ein Commit für eine Transaktion durchgeführt oder ein Rollback ausgeführt wurde, müssen Sie den Schlüssel mithilfe von RegCreateKeyTransacted oder RegOpenKeyTransacted mit einem aktiven Transaktionshandle erneut öffnen, um zusätzliche Vorgänge durchzuführen. Weitere Informationen zu Transaktionen finden Sie unter Kerneltransaktions-Manager.

Beachten Sie, dass nachfolgende Vorgänge für Unterschlüssel dieses Schlüssels nicht automatisch durchgeführt werden. Daher führt RegDeleteKeyEx keinen Transaktionslöschvorgang aus. Verwenden Sie stattdessen die RegDeleteKeyTransacted-Funktion , um einen Transaktionslöschvorgang auszuführen.

Der Schlüssel, den die RegCreateKeyTransacted-Funktion erstellt, weist keine Werte auf. Eine Anwendung kann die RegSetValueEx-Funktion verwenden, um Schlüsselwerte festzulegen.

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

Hinweis

Der winreg.h-Header definiert RegCreateKeyTransacted 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


Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winreg.h (Windows.h einschließen)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll