RegQueryValueExA-Funktion (winreg.h)

Artikel
03/11/2023

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, wird 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 nachstehenden Hinweisen.

Syntax

LSTATUS RegQueryValueExA(
  [in]                HKEY    hKey,
  [in, optional]      LPCSTR  lpValueName,
                      LPDWORD lpReserved,
  [out, optional]     LPDWORD lpType,
  [out, optional]     LPBYTE  lpData,
  [in, out, optional] LPDWORD lpcbData
);

Parameter

[in] hKey

Ein Handle für einen geöffneten Registrierungsschlüssel. Der Schlüssel muss mit dem Zugriffsrecht KEY_QUERY_VALUE geöffnet worden sein. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für Registrierungsschlüssel.

Dieses Handle wird von der RegCreateKeyEx-, RegCreateKeyTransacted-, RegOpenKeyEx- oder RegOpenKeyTransacted-Funktion zurückgegeben. Es kann auch einer der folgenden vordefinierten Schlüssel sein:

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 lpValueNameNULL oder eine leere Zeichenfolge ist, ruft die Funktion den Typ und die Daten für den unbenannten oder Standardwert des Schlüssels ab, falls vorhanden.

Wenn lpValueName einen Wert angibt, der nicht in der Registrierung enthalten ist, gibt die Funktion ERROR_FILE_NOT_FOUND zurück.

Schlüssel weisen nicht automatisch einen unbenannten oder Standardwert auf. Unbenannte Werte können einen beliebigen Typ aufweisen. Weitere Informationen finden Sie unter Größenbeschränkungen für Registrierungselemente.

lpReserved

Dieser Parameter ist reserviert und muss NULL sein.

[out, optional] lpType

Ein Zeiger auf eine Variable, die einen Code empfängt, der den Typ der im angegebenen Wert gespeicherten Daten angibt. Eine Liste der möglichen Typcodes finden Sie unter Registrierungswerttypen. Der lpType-Parameter 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 sein, 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 Bytes verweist. Wenn die Funktion zurückgibt, enthält diese Variable die Größe der in lpData kopierten Daten.

Der lpcbData-Parameter kann nur NULL sein, wenn lpDataNULL ist.

Wenn die Daten über den typ REG_SZ, REG_MULTI_SZ oder REG_EXPAND_SZ verfügen, umfasst diese Größe alle endenden NULL-Zeichen oder Zeichen, es sei denn, die Daten wurden ohne diese gespeichert. Weitere Informationen finden Sie in den Hinweisen.

Wenn der durch den 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 von lpcbData verwiesen wird. In diesem Fall ist der Inhalt des lpData-Puffers nicht definiert.

Wenn lpDataNULL und lpcbData ungleich NULL ist, gibt die Funktion ERROR_SUCCESS zurück und speichert die Größe der Daten in Bytes in der Variablen, auf die von lpcbData verwiesen wird. Dadurch kann eine Anwendung die beste Methode zum Zuordnen eines Puffers für die Daten des Werts ermitteln.

Wenn hKeyHKEY_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 über den lpcbData-Parameter 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 aufrufen und die aktualisierte Puffergröße im lpcbData-Parameter übergeben. Wiederholen Sie dies, bis die Funktion erfolgreich ist. Sie müssen eine separate Variable verwalten, um die Puffergröße nachzuverfolgen, da der von lpcbData zurückgegebene Wert unvorhersehbar ist.

Wenn der Registrierungswert lpValueName nicht vorhanden ist, gibt RegQueryValueEx ERROR_FILE_NOT_FOUND zurück, und der wert, der über den lpcbData-Parameter zurückgegeben wird, 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 Registrierungswert lpValueName 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 über den REG_SZ, REG_MULTI_SZ oder REG_EXPAND_SZ Typ verfügen, wurde die Zeichenfolge möglicherweise nicht mit den richtigen endenden NULL-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 enthalten sollten.) Eine Möglichkeit, wie eine Anwendung sicherstellen kann, dass die Zeichenfolge ordnungsgemäß beendet wird, besteht darin, RegGetValue zu verwenden, wodurch bei Bedarf beendete NULL-Zeichen hinzugefügt werden.

Wenn die Daten den typ REG_SZ, REG_MULTI_SZ oder REG_EXPAND_SZ haben und die ANSI-Version dieser Funktion verwendet wird (entweder durch expliziten Aufruf von RegQueryValueExA oder durch nicht definierende 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 lpData verweist.

Wenn Sie die RegQueryValueEx-Funktion aufrufen, wobei hKey auf das HKEY_PERFORMANCE_DATA Handle und eine Wertzeichenfolge eines angegebenen Objekts festgelegt ist, enthält die zurückgegebene Datenstruktur manchmal nicht angeforderte Objekte. Wundern Sie sich nicht; Dies ist ein normales Verhalten. Beim Aufrufen der RegQueryValueEx-Funktion sollten Sie immer erwarten, 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 Registrierungsvirtualisierung und 32-Bit- und 64-Bit-Anwendungsdaten in der Registrierung.

Beispiele

Stellen Sie sicher, dass Sie den Wert, auf den der lpcbData-Parameter verweist, jedes Mal erneut initialisieren, wenn Sie diese Funktion aufrufen. Dies ist sehr wichtig, wenn Sie diese Funktion in einer Schleife aufrufen, wie im folgenden Codebeispiel gezeigt.

#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);
}

Hinweis

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 Aliases 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


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winreg.h (Windows.h einschließen)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll