SHRegGetValueA-Funktion (shlwapi.h)

  • Artikel

[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 derzeit 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-endende 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-endende 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 eines der SRRF-Flags , das die abzurufenden Daten einschränkt. Es muss mindestens ein Typeinschränkungswert (SRRF_RT) angegeben werden.

[in, out] pdwType

Typ: LPDWORD

Ein Zeiger auf ein DWORD , das den Typ der im abgerufenen Wert gespeicherten Daten empfängt. Bei Verwendung von Standardwerten ist der 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 keine Typinformationen 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 auf die Existenz eines Werts testen würden, wären die spezifischen Wertdaten überflüssig.

[in, out] pcbData

Typ: LPDWORD

Ein Zeiger auf ein DWORD , das beim Eintrag die Größe des Zieldatenpuffers pvData in Byte enthält. Dieser Wert kann nur NULL sein, wenn pvDataNULL ist. Beim Beenden zeigt pcbData auf einen dieser Werte.

pvData Rückgabewert pcbData
NULL ERROR_SUCCESS Größe in Bytes, die ausreicht, um die Registrierungsdaten zu enthalten. Beachten Sie, dass dies nicht garantiert die genaue Größe, sondern nur eine ausreichende Größe ist.
Ungleich NULL ERROR_SUCCESS Genaue Anzahl von Bytes, die in pvData geschrieben werden.
Ungleich NULL ERROR_MORE_DATA Größe in Bytes, die benötigt wird, um die gesamten Daten zu enthalten. Beachten Sie, dass dies nicht garantiert die genaue Größe, sondern nur eine ausreichende Größe ist.

Rückgabewert

Typ: LSTATUS

Gibt bei erfolgreicher Ausführung ERROR_SUCCESS oder andernfalls einen in Winerror.h definierten Fehlercode ungleich null zurück. Sie können die FormatMessage-Funktion mit dem flag FORMAT_MESSAGE_FROM_SYSTEM verwenden, um eine generische Beschreibung des Fehlers abzurufen.

Hinweise

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

Der durch 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 Typ der Daten REG_SZ, REG_EXPAND_SZ oder REG_MULTI_SZ ist, enthalten oder berücksichtigen alle zurückgegebenen Daten die NULL-Beendigung der Zeichenfolge. Wenn pvData beispielsweise nicht NULL ist, sind die in diesem Puffer zurückgegebenen Daten null-terminiert. Wenn pcbData nicht NULL ist, enthält die Puffergröße, auf die sie verweist, die Bytes, die erforderlich sind, um das abschließende NULL-Zeichen zu enthalten.

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 von 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 von dieser Funktion bei jedem Zugriff 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 ShRegGetValue aufgerufen wird. Verwenden Sie den im phkResult-Parameter von RegOpenKeyEx zurückgegebenen Schlüssel als hkey-Parameter in dieser Funktion, wobei pszSubKey auf NULL festgelegt ist.

Die Möglichkeit für einen zusätzlichen Aufruf der Registrierung zum Lesen oder erneuten Lesen der Daten besteht, wenn der Datentyp REG_EXPAND_SZ ist und das flag SRRF_NOEXPAND 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 wird erweitert, um die erforderliche Größe des Datenpuffers zu bestimmen.
  • 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 erforderliche Gesamtgröß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ä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 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