RegQueryMultipleValuesA-Funktion (winreg.h)

  • Artikel

Ruft den Typ und die Daten für eine Liste von Wertnamen ab, die einem geöffneten Registrierungsschlüssel zugeordnet sind.

Syntax

LSTATUS RegQueryMultipleValuesA(
  [in]                HKEY     hKey,
  [out]               PVALENTA val_list,
  [in]                DWORD    num_vals,
  [out, optional]     LPSTR    lpValueBuf,
  [in, out, optional] LPDWORD  ldwTotsize
);

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

Registrierungsschlüsselsicherheit und -zugriffsrechte.

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_USERS

[out] val_list

Ein Zeiger auf ein Array von

VALENT-Strukturen , die einen oder mehrere Werteinträge beschreiben. Bei der Eingabe muss das ve_valuename Member jeder Struktur einen Zeiger auf den Namen eines abzurufenden Werts enthalten. Die Funktion schlägt fehl, wenn einer der angegebenen Werte im angegebenen Schlüssel nicht vorhanden ist.

Wenn die Funktion erfolgreich ist, enthält jedes Element des Arrays die Informationen für den angegebenen Wert.

[in] num_vals

Die Anzahl der Elemente im val_list Arrays.

[out, optional] lpValueBuf

Ein Zeiger auf einen Puffer. Wenn die Funktion erfolgreich ist, empfängt der Puffer die Daten für jeden Wert.

Wenn lpValueBufNULL ist, muss der Wert, auf den der parameter ldwTotsize verweist, null sein. In diesem Fall gibt die Funktion ERROR_MORE_DATA zurück, und ldwTotsize empfängt die erforderliche Größe des Puffers in Bytes.

[in, out, optional] ldwTotsize

Ein Zeiger auf eine Variable, der die Größe des Puffers angibt, auf den der lpValueBuf-Parameter in Bytes verweist. Wenn die Funktion erfolgreich ist, empfängt ldwTotsize die Anzahl der Bytes, die in den Puffer kopiert wurden. Wenn die Funktion fehlschlägt, weil der Puffer zu klein ist, empfängt ldwTotsize die erforderliche Größe in Bytes.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.

Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der folgenden Fehlercodes.

Rückgabecode Beschreibung
ERROR_CANTREAD

RegQueryMultipleValues kann nicht instanziieren oder auf den Anbieter des dynamischen Schlüssels zugreifen.
ERROR_MORE_DATA
 Der Puffer, auf den lpValueBuf verweist, war zu klein. In diesem Fall erhält ldwTotsize die erforderliche Puffergröße.
ERROR_TRANSFER_TOO_LONG
 Die Gesamtgröße der angeforderten Daten (Größe des val_list Arrays + ldwTotSize) liegt über dem Systemlimit von einem Megabyte.

Hinweise

Mit der RegQueryMultipleValues-Funktion kann eine Anwendung einen oder mehrere Werte eines statischen oder dynamischen Schlüssels abfragen. Wenn der Zielschlüssel ein statischer Schlüssel ist, stellt das System alle Werte auf atomare Weise bereit. Um übermäßige Serialisierung zu verhindern, dürfen die von der Funktion zurückgegebenen aggregierten Daten ein Megabyte nicht überschreiten.

Wenn der Zielschlüssel ein dynamischer Schlüssel ist, muss sein Anbieter alle Werte auf atomare Weise bereitstellen. Dies bedeutet, dass der Anbieter den Ergebnispuffer synchron füllen sollte, um eine konsistente Ansicht aller Werte im Puffer bereitzustellen und gleichzeitig übermäßige Serialisierung zu vermeiden. Der Anbieter kann während eines atomaren Aufrufs dieser Funktion maximal ein Megabyte an Ausgabedaten bereitstellen.

RegQueryMultipleValues wird remote unterstützt. Das heißt, der an die Funktion übergebene hKey-Parameter kann auf einen Remotecomputer verweisen.

Hinweis

Der winreg.h-Header definiert RegQueryMultipleValues als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code 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 (einschließlich Windows.h)
Bibliothek Advapi32.lib
DLL Advapi32.dll

Weitere Informationen

Registrierungsfunktionen

Registrierungsübersicht

VALENT