RegQueryMultipleValuesA-Funktion (winreg.h)

Artikel
11/20/2024

Ruft den Typ und die Daten für eine Liste mit 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 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_USERS

[out] val_list

Ein Zeiger auf ein Array von

VALENT Strukturen, die einen oder mehrere Werteinträge beschreiben. Bei eingaben muss das ve_valuename Element jeder Struktur einen Zeiger auf den Namen eines abzurufenden Werts enthalten. Die Funktion schlägt fehl, wenn eine 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 Array.

[out, optional] lpValueBuf

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

Wenn lpValueBuf-NULL-ist, muss der Wert, auf den der ldwTotsize-Parameter verweist, null sein, in diesem Fall gibt die Funktion ERROR_MORE_DATA zurück und ldwTotsize erhält die erforderliche Größe des Puffers in Byte.

[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, erhält ldwTotsize die Anzahl der in den Puffer kopierten Bytes. Wenn die Funktion fehlschlägt, da der Puffer zu klein ist, erhält 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) ist mehr als die Systemgrenze von einem Megabyte.

Bemerkungen

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 atomische Weise bereit. Um eine übermäßige Serialisierung zu verhindern, dürfen die von der Funktion zurückgegebenen Aggregatdaten nicht ein Megabyte überschreiten.

Wenn der Zielschlüssel ein dynamischer Schlüssel ist, muss sein Anbieter alle Werte in atomer Weise bereitstellen. Dies bedeutet, dass der Anbieter den Ergebnispuffer synchron ausfüllen sollte, wodurch eine konsistente Ansicht aller Werte im Puffer bereitgestellt wird, während eine übermäßige Serialisierung vermieden wird. Der Anbieter kann während eines atomischer Aufrufs dieser Funktion höchstens ein Megabyte gesamter Ausgabedaten bereitstellen.

RegQueryMultipleValues wird remote unterstützt; d. h. der hKey Parameter, der an die Funktion übergeben wird, kann auf einen Remotecomputer verweisen.

Anmerkung

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

Siehe auch

Registrierungsfunktionen

Registrierungsübersicht

VALENT

Freigeben über