RegCreateKeyTransactedA-Funktion (winreg.h)
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 |
|---|---|
|
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. |
|
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. |
|
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.
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 |