RegOpenKeyExA-Funktion (winreg.h)

Artikel
11/20/2024

Öffnet den angegebenen Registrierungsschlüssel. Beachten Sie, dass bei Schlüsselnamen die Groß-/Kleinschreibung nicht beachtet wird.

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

Syntax

LSTATUS RegOpenKeyExA(
  [in]           HKEY   hKey,
  [in, optional] LPCSTR lpSubKey,
  [in]           DWORD  ulOptions,
  [in]           REGSAM samDesired,
  [out]          PHKEY  phkResult
);

Parameter

[in] hKey

Ein Handle zu einem geöffneten Registrierungsschlüssel. Dieses Handle wird von der RegCreateKeyEx-- oder RegOpenKeyEx--Funktion zurückgegeben, oder es kann sich um einen der folgenden vordefinierten Schlüssel:

HKEY_CLASSES_ROOTHKEY_CURRENT_CONFIGHKEY_CURRENT_USERHKEY_LOCAL_MACHINEHKEY_USERS

[in, optional] lpSubKey

Der Name des Registrierungsunterschlüssels, der geöffnet werden soll.

Bei Schlüsselnamen wird die Groß-/Kleinschreibung nicht beachtet.

Wenn der parameter lpSubKeyNULL oder ein Zeiger auf eine leere Zeichenfolge ist und hKey ein vordefinierter Schlüssel ist, aktualisiert das System den vordefinierten Schlüssel, und phkResult erhält denselben hKey-, der an die Funktion übergeben wird. Andernfalls empfängt phkResult ein neues Handle für den geöffneten Schlüssel.

Weitere Informationen finden Sie unter Registrierungselementgrößenbeschränkungen.

[in] ulOptions

Gibt die Option an, die beim Öffnen der Taste angewendet werden soll. Legen Sie diesen Parameter auf Null oder Folgendes fest:

Wert	Bedeutung
REG_OPTION_OPEN_LINK	Der Schlüssel ist eine symbolische Verbindung. Symbolische Verknüpfungen der Registrierung sollten nur verwendet werden, wenn sie unbedingt erforderlich sind.

[in] samDesired

Eine Maske, die die gewünschten Zugriffsrechte für den zu öffnenden Schlüssel angibt. Die Funktion schlägt fehl, wenn der Sicherheitsdeskriptor des Schlüssels den angeforderten Zugriff für den Aufrufvorgang nicht zulässt. Weitere Informationen finden Sie unter Registry Key Security and Access Rights.

[out] phkResult

Ein Zeiger auf eine Variable, die ein Handle für den geöffneten 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.

Anmerkung

In älteren Versionen von Windows wird diese API auch von kernel32.dllverfügbar gemacht.

Bemerkungen

Im Gegensatz zur RegCreateKeyEx--Funktion erstellt die RegOpenKeyEx- Funktion nicht den angegebenen Schlüssel, wenn der Schlüssel nicht in der Registrierung vorhanden ist.

Bestimmte Registrierungsvorgänge führen Zugriffsüberprüfungen mit dem Sicherheitsdeskriptor des Schlüssels aus, nicht mit der Zugriffsmaske, die beim Abrufen des Handles für den Schlüssel angegeben wurde. Selbst wenn ein Schlüssel mit einem samDesired von KEY_READ geöffnet wird, kann er verwendet werden, um Registrierungsschlüssel zu erstellen, wenn der Sicherheitsdeskriptor des Schlüssels zulässt. Im Gegensatz dazu erfordert die RegSetValueEx--Funktion ausdrücklich, dass der Schlüssel mit dem KEY_SET_VALUE Zugriffsrecht geöffnet wird.

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.

Beispiele

lResult = RegOpenKeyEx (hKeyRoot, lpSubKey, 0, KEY_READ, &hKey);

if (lResult != ERROR_SUCCESS) 
{
    if (lResult == ERROR_FILE_NOT_FOUND) {
        printf("Key not found.\n");
        return TRUE;
    } 
    else {
        printf("Error opening key.\n");
        return FALSE;
    }
}

Informationen zum Anzeigen dieses Beispiels im Kontext finden Sie unter Löschen eines Schlüssels mit Unterschlüsseln.

Anmerkung

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