RegCreateKeyExA-Funktion (winreg.h)
Erstellt den angegebenen Registrierungsschlüssel. 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.
Rufen Sie die RegCreateKeyTransacted-Funktion auf, um transaktionsierte Registrierungsvorgänge für einen Schlüssel auszuführen.
Anwendungen, die den Systemzustand sichern oder wiederherstellen, einschließlich Systemdateien und Registrierungsstrukturen, sollten anstelle der Registrierungsfunktionen den Volumeschattenkopiedienst 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 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 er daher in Vorgängen verwendet werden, die die Registrierung ändern, 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] 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 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
Der benutzerdefinierte Klassentyp 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 parameter samDesired 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 den Zugriffsrechten KEY_READ geöffnet. Wenn für den aufrufenden Thread die Berechtigung SE_RESTORE_NAME aktiviert ist, wird der Schlüssel ab Windows Vista mit den Zugriffsrechten ACCESS_SYSTEM_SECURITY, DELETE und KEY_WRITE 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. |
|
Hinweis Symbolische Registrierungslinks sollten aus Gründen der Anwendungskompatibilität nur verwendet werden, wenn dies unbedingt erforderlich ist.
|
|
Dieser Schlüssel ist nicht flüchtig. Dies ist die Standardeinstellung. Die Informationen werden in einer Datei gespeichert und beim Neustart des Systems beibehalten. Die RegSaveKey-Funktion speichert Schlüssel, die nicht flüchtig 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 nur auf, wenn das System ein vollständiges Herunterfahren initiiert. 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 schlüssel ignoriert, die bereits vorhanden sind.
Hinweis Wenn ein Benutzer das Herunterfahren ausgewählt hat, ist ein schnelles Herunterfahren das Standardverhalten für das System.
|
[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.
Der lpSecurityDescriptor-Member der -Struktur gibt einen Sicherheitsdeskriptor für den neuen Schlüssel an. Wenn lpSecurityAttributesNULL ist, ruft der Schlüssel einen Standardsicherheitsdeskriptor ab. 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 keiner der vordefinierten Registrierungsschlüssel ist, rufen Sie die RegCloseKey-Funktion auf, nachdem Sie das Handle verwendet haben.
[out, optional] lpdwDisposition
Ein Zeiger auf eine Variable, die einen der folgenden Dispositionswerte empfängt.
Wenn lpdwDispositionNULL ist, werden keine Dispositionsinformationen 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 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
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. 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.
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.
Beachten Sie, dass Vorgänge, die auf bestimmte Registrierungsschlüssel zugreifen, umgeleitet werden. Weitere Informationen finden Sie unter Registrierungsvirtualisierungund 32-Bit- und 64-Bit-Anwendungsdaten in der Registrierung.
Hinweis
Der winreg.h-Header definiert RegCreateKeyEx 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
| 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 (einschließlich Windows.h) |
| Bibliothek | Advapi32.lib |
| DLL | Advapi32.dll |