SHRegQueryUSValueA-Funktion (shlwapi.h)

Artikel
11/20/2024

Ruft den Typ und die Daten für einen angegebenen Namen ab, der einem geöffneten Registrierungsunterschlüssel in einer benutzerspezifischen Unterstruktur (HKEY_CURRENT_USER oder HKEY_LOCAL_MACHINE) zugeordnet ist.

Syntax

LSTATUS SHRegQueryUSValueA(
  [in]                HUSKEY hUSKey,
  [in, optional]      LPCSTR pszValue,
  [in, out, optional] DWORD  *pdwType,
  [out, optional]     void   *pvData,
  [in, out]           DWORD  *pcbData,
  [in]                BOOL   fIgnoreHKCU,
  [in, optional]      void   *pvDefaultData,
  [in, optional]      DWORD  dwDefaultDataSize
);

Parameter

[in] hUSKey

Typ: HUSKEY

Ein Handle zu einem aktuell geöffneten Registrierungsunterschlüssel oder einem der folgenden vordefinierten Werte. Der Unterschlüssel muss mit dem KEY_SET_VALUE Zugriffsrecht geöffnet worden sein. Weitere Informationen finden Sie unter Registry Key Security and Access Rights.

Dieses Handle kann über die SHRegOpenUSKey--Funktion abgerufen werden.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in, optional] pszValue

Typ: LPCTSTR-

Ein Zeiger auf die NULL--terminated-Zeichenfolge, die den Namen des zu abfragenden Werts enthält.

[in, out, optional] pdwType

Typ: LPDWORD*

Ein Zeiger auf die Variable, die den Werttyp des Schlüssels festlegt oder empfängt. Weitere Informationen finden Sie unter Registrierungsdatentypen. Dieser Parameter kann NULL-sein.

[out, optional] pvData

Typ: LPVOID*

Ein Zeiger auf den Puffer, der die Daten des Werts empfängt. Dieser Parameter kann NULL- werden, wenn die Daten nicht erforderlich sind.

[in, out] pcbData

Typ: LPDWORD*

Ein Zeiger auf die Variable, der die Größe des Puffers in Byte angibt, auf den der pvData--Parameter verweist. Wenn die Funktion zurückgegeben wird, enthält diese Variable die Größe der Daten, die in pvData-kopiert wurden.

[in] fIgnoreHKCU

Typ: BOOL-

Die Variable, die angibt, unter welchem Schlüssel gesucht werden soll. Wenn dieser Wert auf TRUEfestgelegt ist, ignoriert SHRegQueryUSValueHKEY_CURRENT_USER und gibt den Wert aus dem Schlüssel unter HKEY_LOCAL_MACHINEzurück.

[in, optional] pvDefaultData

Typ: LPVOID*

Ein Zeiger auf die Standarddaten.

[in, optional] dwDefaultDataSize

Typ: DWORD-

Die Länge der Standarddaten in Bytes.

Rückgabewert

Typ: LSTATUS-

Gibt ERROR_SUCCESS zurück, wenn dies erfolgreich ist, oder wenn der Fehlercode nicht in Winerror.h definiert ist. Sie können die FormatMessage--Funktion mit dem FORMAT_MESSAGE_FROM_SYSTEM Flag verwenden, um eine generische Beschreibung des Fehlers abzurufen.

Bemerkungen

Wenn fIgnoreHKCU- auf TRUEfestgelegt ist, gibt SHRegQueryUSValue den Wert aus dem Schlüssel unter HKEY_LOCAL_MACHINEzurück. Wenn dieser Wert auf FALSEfestgelegt ist, versucht SHRegQueryUSValue zuerst, den Wert aus dem Schlüssel unter HKEY_CURRENT_USERzurückzugeben. Wenn der Schlüssel jedoch unter HKEY_CURRENT_USERnicht gefunden wird, gibt der Wert aus dem Schlüssel unter HKEY_LOCAL_MACHINEzurück. Wenn kein Schlüssel vorhanden ist oder wenn ein Fehler auftritt und dwDefaultDataSize ungleich Null ist, werden die Standarddaten in pvData- kopiert und ERROR_SUCCESS zurückgegeben. ERROR_SUCCESS gibt sowohl für Standarddaten als auch für nicht standardmäßige Daten zurück, und es gibt keine Möglichkeit zu unterscheiden, welcher Wert in pvData-kopiert wird. Um die Verwendung von Standarddaten zu verhindern, legen Sie pvDefaultData- auf null NULL- und dwDefaultDataSize auf Null fest.

Wenn Sie nur einen einzelnen Wert lesen müssen, öffnet SHRegGetUSValue den Schlüssel und gibt den Wert zurück. Um SHRegQueryUSValuezu verwenden, müssen Sie zuerst den Schlüssel mit SHRegOpenUSKeyöffnen. Sobald der Schlüssel jedoch geöffnet wurde, können Sie SHRegQueryUSValue so oft wie nötig verwenden. Wenn Sie mehrere Werte aus demselben Schlüssel abrufen müssen, ist die Verwendung mehrerer Aufrufe an SHRegQueryUSValue in der Regel effizienter als SHRegGetUSValue, da der Schlüssel nur einmal geöffnet wird.

Anmerkung

Der Header "shlwapi.h" definiert SHRegQueryUSValue 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, Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	shlwapi.h
Library	Shlwapi.lib
DLL-	Shlwapi.dll (Version 4.71 oder höher)

Freigeben über