SHRegGetValueA-Funktion (shlwapi.h)

Artikel
11/20/2024

[SHRegGetValue kann in nachfolgenden Versionen des Betriebssystems oder Produkts geändert oder nicht verfügbar sein. Verwenden Sie RegGetValue- an seiner Stelle.]

Ruft einen Registrierungswert ab.

Syntax

LSTATUS SHRegGetValueA(
  [in]      HKEY   hkey,
  [in]      LPCSTR pszSubKey,
  [in]      LPCSTR pszValue,
  [in]      SRRF   srrfFlags,
  [in, out] DWORD  *pdwType,
  [out]     void   *pvData,
  [in, out] DWORD  *pcbData
);

Parameter

[in] hkey

Typ: HKEY-

Ein Handle für den aktuell geöffneten Schlüssel oder einen der folgenden vordefinierten Werte.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in] pszSubKey

Typ: LPCTSTR-

Ein Zeiger auf eine NULL--terminated-Zeichenfolge, die den relativen Pfad von hkey- zum Unterschlüssel angibt, aus dem der Wert abgerufen werden soll. Dieser Parameter kann NULL- oder eine leere Zeichenfolge sein. In diesem Fall werden die Daten aus dem hkey Speicherort abgerufen.

[in] pszValue

Typ: LPCTSTR-

Ein Zeiger auf eine NULL--terminated-Zeichenfolge, die den Namen des Werts enthält. Dieser Parameter kann NULL- oder eine leere Zeichenfolge sein, in diesem Fall werden die Daten aus dem Standardwert abgerufen.

[in] srrfFlags

Typ: SRRF-

Mindestens ein SRRF- Flags, mit denen die abzurufenden Daten eingeschränkt werden. Es muss mindestens ein Typeinschränkungswert (SRRF_RT) angegeben werden.

[in, out] pdwType

Typ: LPDWORD-

Ein Zeiger auf eine DWORD-, die den Datentyp empfängt, der im abgerufenen Wert gespeichert ist. Bei Verwendung von Standardwerten ist die Eingabe pdwType- der Typ des Standardwerts. Mögliche Werte finden Sie unter Registrierungsdatentypen. Wenn das SRRF_NOEXPAND Flag nicht festgelegt ist, werden REG_EXPAND_SZ Typen automatisch erweitert und als REG_SZ zurückgegeben. Wenn Typinformationen nicht erforderlich sind, kann dieser Parameter NULL-werden.

[out] pvData

Typ: LPVOID-

Ein Zeiger auf einen Puffer, der die Daten des Werts empfängt. Dieser Parameter kann NULL- werden, wenn die Daten nicht benötigt werden. Wenn Sie beispielsweise nur auf das Vorhandensein eines Werts testen würden, wären die spezifischen Wertdaten überflüssig.

[in, out] pcbData

Typ: LPDWORD-

Ein Zeiger auf eine DWORD-, die beim Eintrag die Größe des Zieldatenpuffers pvData-in Byte enthält. Dieser Wert kann nur NULL- werden, wenn pvData-NULL-ist. Beim Verlassen zeigt pcbData auf einen dieser Werte.

pvData	Rückgabewert	pcbData
NULL-	ERROR_SUCCESS	Größe in Bytes, die ausreichen, um die Registrierungsdaten zu enthalten. Beachten Sie, dass dies nicht garantiert die genaue Größe, sondern nur eine ausreichende Größe ist.
NichtNULL-	ERROR_SUCCESS	Genaue Anzahl von Bytes, die in pvData-geschrieben wurden.
NichtNULL-	ERROR_MORE_DATA	Größe in Bytes, die zum Halten der gesamten Daten erforderlich sind. Beachten Sie, dass dies nicht garantiert die genaue Größe, sondern nur eine ausreichende Größe ist.

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 allgemeine Beschreibung des Fehlers abzurufen.

Bemerkungen

SHRegGetValue bietet die Datentypüberprüfung, Startmodusüberprüfung, automatische Erweiterung REG_EXPAND_SZ Daten und garantierte NULL--Beendigung von REG_SZ, REG_EXPAND_SZ und REG_MULTI_SZ Daten.

Der von hkey- identifizierte Schlüssel muss mit KEY_QUERY_VALUE Sicherheitszugriff geöffnet worden sein. Wenn pszSubKey- nicht NULL- oder eine leere Zeichenfolge ist, muss dieser Schlüssel auch mit KEY_QUERY_VALUE Sicherheitszugriff im aktuellen aufrufenden Kontext geöffnet werden können.

Wenn der Datentyp REG_SZ, REG_EXPAND_SZ oder REG_MULTI_SZ ist, enthält oder berücksichtigt jede zurückgegebene Daten die null-termination der Zeichenfolge. Wenn beispielsweise pvData- nicht NULL-ist, werden die in diesem Puffer zurückgegebenen Daten NULL--terminated. Wenn pcbData- nicht NULL-ist, enthält die Puffergröße, die darauf verweist, die Bytes, die zum Speichern des Endzeichens Null zeichen erforderlich sind.

Sofern das SRRF_NOEXPAND Flag nicht festgelegt ist, werden Zeichenfolgendaten vom Typ REG_EXPAND_SZ automatisch erweitert, bevor sie zurückgegeben werden. Der Typ der erweiterten Zeichenfolge wird in pdwType als REG_SZ gemeldet, der pcbData Parameter verweist auf die Anzahl der Bytes, die für die erweiterte Zeichenfolge geschrieben wurden, und der Puffer, auf den pvData- verweist, enthält die erweiterte Version der Zeichenfolge.

Leistungshinweise

Wenn pszSubKey nicht NULL- oder eine leere Zeichenfolge ist, wird dieser Schlüssel bei jedem Zugriff durch diese Funktion geöffnet und geschlossen. Wenn Ihre Anwendung eine Reihe von Werten aus demselben Unterschlüssel abrufen muss, sehen Sie eine bessere Leistung, indem Sie den Schlüssel mithilfe RegOpenKeyEx- öffnen, bevor Sie SHRegGetValueaufrufen. Verwenden Sie den schlüssel, der im phkResult Parameter von RegOpenKeyEx als hkey Parameter in dieser Funktion zurückgegeben wird, wobei pszSubKey auf NULL-festgelegt ist.

Das Potenzial für einen zusätzlichen Aufruf der Registrierung zum Lesen oder erneuten Lesen der Daten ist vorhanden, wenn der Datentyp REG_EXPAND_SZ ist und das SRRF_NOEXPAND Flag nicht festgelegt wurde. Die folgenden Bedingungen führen zu diesem zusätzlichen Aufruf.

pvData- ist NULL, pcbData- ist nicht NULL-. Obwohl die Daten nicht abgerufen werden, muss die Registrierung gelesen werden, um die Zeichenfolge abzurufen und diese Zeichenfolge erweitert, um die erforderliche Größe des Datenpuffers zu ermitteln.
pvData- ist nicht NULL-, sondern zu klein, um die Daten zu speichern. Die Daten werden erneut gelesen, um die vollständige Zeichenfolge abzurufen, die Zeichenfolge wird erweitert, und die gesamt erforderliche Größe wird bestimmt.

Anmerkung

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

Siehe auch

RegQueryValueEx-

Freigeben über