RegQueryValueExW-Funktion (winreg.h)
Ruft den Typ und die Daten für den angegebenen Wertnamen ab, der einem geöffneten Registrierungsschlüssel zugeordnet ist.
Warnung
Wenn es sich bei dem abgefragten Wert um eine Zeichenfolge (REG_SZ, REG_MULTI_SZ und REG_EXPAND_SZ) handelt, ist der zurückgegebene Wert NICHT garantiert null-beendet. Verwenden Sie die RegGetValue--Funktion, wenn Sie sicherstellen möchten, dass zurückgegebene Zeichenfolgenwerte null-beendet sind. Weitere Informationen finden Sie in den anmerkungen unten.
Syntax
LSTATUS RegQueryValueExW(
[in] HKEY hKey,
[in, optional] LPCWSTR lpValueName,
LPDWORD lpReserved,
[out, optional] LPDWORD lpType,
[out, optional] LPBYTE lpData,
[in, out, optional] LPDWORD lpcbData
);
Parameter
[in] hKey
Ein Handle zu einem geöffneten Registrierungsschlüssel. Der Schlüssel muss mit dem zugriffsrecht KEY_QUERY_VALUE geöffnet worden sein. Weitere Informationen finden Sie unter Registry Key Security and Access Rights.
Dieses Handle wird von der RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyExoder RegOpenKeyTransacted Funktion zurückgegeben. Es kann auch einer der folgenden vordefinierten Schlüsselsein:
- HKEY_CLASSES_ROOT
- HKEY_CURRENT_CONFIG
- HKEY_CURRENT_USER
- HKEY_LOCAL_MACHINE
- HKEY_PERFORMANCE_DATA
- HKEY_PERFORMANCE_NLSTEXT
- HKEY_PERFORMANCE_TEXT
- HKEY_USERS
[in, optional] lpValueName
Der Name des Registrierungswerts.
Wenn lpValueName-NULL- oder eine leere Zeichenfolge "" ist, ruft die Funktion ggf. den Typ und die Daten für den unbenannten oder Standardwert des Schlüssels ab.
Wenn lpValueName einen Wert angibt, der nicht in der Registrierung enthalten ist, gibt die Funktion ERROR_FILE_NOT_FOUND zurück.
Schlüssel verfügen nicht automatisch über einen unbenannten oder Standardwert. Unbenannte Werte können beliebiger Art sein. Weitere Informationen finden Sie unter Registrierungselementgrößenbeschränkungen.
lpReserved
Dieser Parameter ist reserviert und muss NULL-sein.
[out, optional] lpType
Ein Zeiger auf eine Variable, die einen Code empfängt, der den Datentyp angibt, der im angegebenen Wert gespeichert ist. Eine Liste der möglichen Typcodes finden Sie unter Registrierungswerttypen. Der parameter lpType kann NULL- sein, wenn der Typcode nicht erforderlich ist.
[out, optional] lpData
Ein Zeiger auf einen Puffer, der die Daten des Werts empfängt. Dieser Parameter kann NULL- werden, wenn die Daten nicht erforderlich sind.
[in, out, optional] lpcbData
Ein Zeiger auf eine Variable, der die Größe des Puffers angibt, auf den der lpData--Parameter in Byte verweist. Wenn die Funktion zurückgegeben wird, enthält diese Variable die Größe der in lpData-kopierten Daten.
Der parameter lpcbData kann nur NULL- sein, wenn lpData-NULL-ist.
Wenn die Daten den REG_SZ, REG_MULTI_SZ oder REG_EXPAND_SZ Typ aufweisen, enthält diese Größe alle endenden NULL-zeichen oder Zeichen Zeichen oder Zeichen, es sei denn, die Daten wurden ohne sie gespeichert. Weitere Informationen finden Sie in den Hinweisen.
Wenn der durch lpData Parameter angegebene Puffer nicht groß genug ist, um die Daten aufzunehmen, gibt die Funktion ERROR_MORE_DATA zurück und speichert die erforderliche Puffergröße in der Variablen, auf die durch lpcbDataverwiesen wird. In diesem Fall sind die Inhalte des lpData- Puffers nicht definiert.
Wenn lpData-NULL-ist und lpcbData- nichtNULL-ist, gibt die Funktion ERROR_SUCCESS zurück und speichert die Größe der Daten in Bytes in der Variablen, auf die durch lpcbDataverweist. Auf diese Weise kann eine Anwendung die beste Methode zum Zuordnen eines Puffers für die Daten des Werts ermitteln.
Wenn hKey-HKEY_PERFORMANCE_DATA angibt und der lpData- Puffer nicht groß genug ist, um alle zurückgegebenen Daten zu enthalten, gibt RegQueryValueEx ERROR_MORE_DATA zurück und der durch den parameter lpcbData zurückgegebene Wert ist nicht definiert. Dies liegt daran, dass sich die Größe der Leistungsdaten von einem Aufruf zum nächsten ändern kann. In diesem Fall müssen Sie die Puffergröße erhöhen und RegQueryValueEx- erneut die aktualisierte Puffergröße im parameter lpcbData übergeben. Wiederholen Sie diesen Vorgang, bis die Funktion erfolgreich ausgeführt wird. Sie müssen eine separate Variable beibehalten, um die Puffergröße nachzuverfolgen, da der von lpcbData zurückgegebene Wert unvorhersehbar ist.
Wenn der lpValueName Registrierungswert nicht vorhanden ist, gibt RegQueryValueEx ERROR_FILE_NOT_FOUND zurück, und der durch den parameter lpcbData zurückgegebene Wert ist nicht definiert.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.
Wenn die Funktion fehlschlägt, ist der Rückgabewert ein Systemfehlercode.
Wenn der lpData- Puffer zu klein ist, um die Daten zu empfangen, gibt die Funktion ERROR_MORE_DATA zurück.
Wenn der lpValueName Registrierungswert nicht vorhanden ist, gibt die Funktion ERROR_FILE_NOT_FOUND zurück.
Bemerkungen
Eine Anwendung ruft in der Regel RegEnumValue auf, um die Wertnamen zu bestimmen, und RegQueryValueEx, um die Daten für die Namen abzurufen.
Wenn die Daten den REG_SZ, REG_MULTI_SZ oder REG_EXPAND_SZ Typ aufweisen, wurde die Zeichenfolge möglicherweise nicht mit dem richtigen Beenden Nullzeichen Zeichen gespeichert. Selbst wenn die Funktion ERROR_SUCCESS zurückgibt, sollte die Anwendung daher sicherstellen, dass die Zeichenfolge ordnungsgemäß beendet wird, bevor sie verwendet wird; andernfalls kann ein Puffer überschrieben werden. (Beachten Sie, dass REG_MULTI_SZ Zeichenfolgen zwei endende null Zeichen aufweisen sollen.) Eine Möglichkeit, um sicherzustellen, dass die Zeichenfolge ordnungsgemäß beendet wird, besteht darin, RegGetValue-zu verwenden, die bei Bedarf das Beenden NULL-Zeichen Zeichen hinzufügt.
Wenn die Daten über die REG_SZ, REG_MULTI_SZ oder REG_EXPAND_SZ Typ verfügen und die ANSI-Version dieser Funktion verwendet wird (entweder durch explizites Aufrufen RegQueryValueExA oder durch Nichtdefinition von UNICODE vor dem Einschließen der Datei Windows.h), konvertiert diese Funktion die gespeicherte Unicode-Zeichenfolge in eine ANSI-Zeichenfolge, bevor sie in den Puffer kopiert wird, auf den lpDataverweist.
Beim Aufrufen der RegQueryValueEx--Funktion mit hKey- auf das handle HKEY_PERFORMANCE_DATA und eine Wertzeichenfolge eines angegebenen Objekts festgelegt ist, weist die zurückgegebene Datenstruktur manchmal nicht angeforderte Objekte auf. Seien Sie nicht überrascht; Dies ist ein normales Verhalten. Beim Aufrufen der RegQueryValueEx--Funktion sollten Sie immer davon ausgehen, dass sie die zurückgegebene Datenstruktur durchlaufen, um nach dem angeforderten Objekt zu suchen.
Beachten Sie, dass Vorgänge, die auf bestimmte Registrierungsschlüssel zugreifen, umgeleitet werden. Weitere Informationen finden Sie unter Registry Virtualization und 32-Bit- und 64-Bit-Anwendungsdaten in der Registrierung.
Beispiele
Stellen Sie sicher, dass Sie den Wert erneut initialisieren, auf den der lpcbData Parameter verweist, wenn Sie diese Funktion aufrufen. Dies ist sehr wichtig, wenn Sie diese Funktion in einer Schleife aufrufen, wie im folgenden Codebeispiel.
#include <windows.h>
#include <malloc.h>
#include <stdio.h>
#define TOTALBYTES 8192
#define BYTEINCREMENT 4096
void main()
{
DWORD BufferSize = TOTALBYTES;
DWORD cbData;
DWORD dwRet;
PPERF_DATA_BLOCK PerfData = (PPERF_DATA_BLOCK) malloc( BufferSize );
cbData = BufferSize;
printf("\nRetrieving the data...");
dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
TEXT("Global"),
NULL,
NULL,
(LPBYTE) PerfData,
&cbData );
while( dwRet == ERROR_MORE_DATA )
{
// Get a buffer that is big enough.
BufferSize += BYTEINCREMENT;
PerfData = (PPERF_DATA_BLOCK) realloc( PerfData, BufferSize );
cbData = BufferSize;
printf(".");
dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
TEXT("Global"),
NULL,
NULL,
(LPBYTE) PerfData,
&cbData );
}
if( dwRet == ERROR_SUCCESS )
printf("\n\nFinal buffer size is %d\n", BufferSize);
else printf("\nRegQueryValueEx failed (%d)\n", dwRet);
}
Anmerkung
Der winreg.h-Header definiert RegQueryValueEx 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 [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform- | Fenster |
| Header- | winreg.h (enthalten Windows.h) |
| Library | Advapi32.lib |
| DLL- | Advapi32.dll |