RegOpenKeyExA-Funktion (winreg.h)

Artikel
03/04/2024

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

Um transaktionsierte Registrierungsvorgänge für einen Schlüssel auszuführen, rufen Sie die RegOpenKeyTransacted-Funktion auf .

Syntax

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

Parameter

[in] hKey

Ein Handle für einen 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 handelt:

HKEY_CLASSES_ROOTHKEY_CURRENT_CONFIGHKEY_CURRENT_USERHKEY_LOCAL_MACHINEHKEY_USERS

[in, optional] lpSubKey

Der Name des zu öffnenden Registrierungsunterschlüssels.

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

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

Weitere Informationen finden Sie unter Größenbeschränkungen für Registrierungselemente.

[in] ulOptions

Gibt die Option an, die beim Öffnen der Taste angewendet werden soll. Legen Sie diesen Parameter auf 0 (null) oder folgendes fest:

Wert	Bedeutung
REG_OPTION_OPEN_LINK	Der Schlüssel ist eine symbolische Verknüpfung. Symbolische Registrierungslinks sollten nur verwendet werden, wenn dies unbedingt erforderlich ist.

[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 aufrufenden Prozess nicht zulässt. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für Registrierungsschlüssel.

[out] phkResult

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

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.

Hinweis

In Legacyversionen von Windows wird diese API auch von kernel32.dll verfügbar gemacht.

Hinweise

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

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

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

Hinweis

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
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 (Windows.h einschließen)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll