SHRegGetValueA-Funktion (shlwapi.h)

[SHRegGetValue kann in nachfolgenden Versionen des Betriebssystems oder Produkts geändert oder nicht verfügbar sein. Verwenden von 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 zum aktuell geöffneten Schlüssel oder eines 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-beendete Zeichenfolge, die den relativen Pfad von hkey zum Unterschlüssel angibt, um den Wert abzurufen. Dieser Parameter kann NULL oder eine leere Zeichenfolge sein, in diesem Fall wird die Daten vom Hkey-Speicherort abgerufen.

[in] pszValue

Typ: LPCTSTR

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

[in] srrfFlags

Typ: SRRF

Mindestens eine der SRRF-Flags , die die abgerufenen Daten einschränken. Mindestens eine Typeinschränkung (SRRF_RT) muss angegeben werden.

[in, out] pdwType

Typ: LPDWORD

Ein Zeiger auf ein DWORD , das 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 Die Typinformationen nicht erforderlich sind, kann dieser Parameter NULL sein.

[out] pvData

Typ: LPVOID

Ein Zeiger auf einen Puffer, der die Daten des Werts empfängt. Dieser Parameter kann NULL sein, wenn die Daten nicht benötigt werden. Wenn Sie beispielsweise nur für die Existenz eines Werts testen, wäre die spezifischen Wertdaten überflüssig.

[in, out] pcbData

Typ: LPDWORD

Ein Zeiger auf ein DWORD , das im Eintrag die Größe des Zieldatenpuffers pvData in Bytes enthält. Dieser Wert kann NUR NULL sein, wenn pvDataNULL ist. Auf exit zeigt pcbData auf einen dieser Werte.

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

Rückgabewert

Typ: LSTATUS

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

Bemerkungen

SHRegGetValue stellt die Überprüfung des Datentyps, die Startmodusüberprüfung, die automatische Erweiterung von REG_EXPAND_SZ Daten und garantierte Null-Beendigung von REG_SZ, REG_EXPAND_SZ und REG_MULTI_SZ Daten bereit.

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 Aufrufkontext geöffnet werden können.

Wenn der Datentyp REG_SZ ist, REG_EXPAND_SZ oder REG_MULTI_SZ, enthält alle zurückgegebenen Daten oder berücksichtigt die Null-Beendigung der Zeichenfolge. Wenn pvData z. B. nicht NULL ist, wird die in diesem Puffer zurückgegebenen Daten null beendet. Wenn pcbData nicht NULL ist, enthält die Puffergröße, die darauf verweist, die bytes, die erforderlich sind, um das endende Nullzeichen zu halten.

Es sei denn, das SRRF_NOEXPAND Flag 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, der von pvData auf die erweiterte Version der Zeichenfolge verweist.

Leistungsnotizen

Wenn pszSubKey nicht NULL oder eine leere Zeichenfolge ist, wird diese Taste 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 von RegOpenKeyEx öffnen, bevor Sie SHRegGetValue aufrufen. Verwenden Sie den im PhkResult-Parameter von RegOpenKeyEx zurückgegebenen Schlüssel als hkey-Parameter in dieser Funktion, wobei pszSubKey auf NULL festgelegt ist.

Das Potenzial für einen zusätzlichen Aufruf der Registrierung, die Daten zu lesen oder neu zu lesen, 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, ist aber zu klein, um die Daten zu halten. Die Daten werden erneut gelesen, um die vollständige Zeichenfolge abzurufen, die Zeichenfolge wird erweitert, und die gesamt erforderliche Größe wird bestimmt.

Hinweis

Der Shlwapi.h-Header definiert SHRegGetValue als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstanten automatisch auswählt. Das Mischen der Verwendung des Codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann dazu führen, dass keine Übereinstimmungen auftreten, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Unterstützte Mindestversion (Client)	Windows XP mit SP2 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	shlwapi.h
Bibliothek	Shlwapi.lib
DLL	Shlwapi.dll (Version 6.0 oder höher)

Weitere Informationen

RegQueryValueEx