OREnumValue-Funktion
Listet die Werte für den angegebenen offenen Registrierungsschlüssel in einer Offlineregistrierungsstruktur auf. Die Funktion ruft bei jedem Aufruf der Funktion Informationen für einen Wert unter dem angegebenen Schlüssel ab.
Syntax
DWORD OREnumValue(
_In_ ORHKEY Handle,
_In_ DWORD dwIndex,
_Out_ PWSTR lpValueName,
_Inout_ PDWORD lpcValueName,
_Out_opt_ PDWORD lpType,
_Out_opt_ PBYTE lpData,
_Inout_opt_ PDWORD lpcbData
);
Parameter
-
Handle [in]
-
Ein Handle für einen geöffneten Registrierungsschlüssel in einer Offlineregistrierungsstruktur.
-
dwIndex [in]
-
Der Index des abzurufenden Werts. Dieser Parameter sollte für den ersten Aufruf der Funktion null und dann für nachfolgende Aufrufe inkrementiert werden.
Da Werte nicht sortiert werden, weist jeder neue Wert einen beliebigen Index auf. Dies bedeutet, dass die Funktion Werte in beliebiger Reihenfolge zurückgeben kann.
-
lpValueName [out]
-
Ein Zeiger auf einen Puffer, der den Namen des Werts als NULL-Zeichenfolge empfängt. Dieser Puffer muss groß genug sein, um das beendende NULL-Zeichen zu enthalten.
Weitere Informationen finden Sie unter Größenbeschränkungen für Registrierungselemente.
-
lpcValueName [in, out]
-
Ein Zeiger auf eine Variable, die die Größe des Puffers angibt, auf den der lpValueName-Parameter in Zeichen verweist. Wenn die Funktion zurückgibt, empfängt die Variable die Anzahl von Zeichen, die im Puffer gespeichert sind, ohne das beendende NULL-Zeichen.
-
lpType [out, optional]
-
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.
-
lpData [out, optional]
-
Ein Zeiger auf einen Puffer, der die Daten für den Werteintrag empfängt. Dieser Parameter kann NULL sein, wenn die Daten nicht erforderlich sind.
Wenn lpDataNULL und lpcbData nicht NULL ist, speichert die Funktion die Größe der Daten in Bytes in der Variablen, auf die von lpcbData verwiesen wird. Dadurch kann eine Anwendung die beste Methode zum Zuweisen eines Puffers für die Daten ermitteln.
-
lpcbData [in, out, optional]
-
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, empfängt die Variable die Anzahl der im Puffer gespeicherten Bytes.
Dieser Parameter kann nur NULL sein, wenn lpDataNULL ist.
Wenn die Daten den Typ REG_SZ, REG_MULTI_SZ oder REG_EXPAND_SZ haben, umfasst diese Größe alle beendenden NULL-Zeichen oder Zeichen. Weitere Informationen finden Sie in den Hinweisen.
Wenn der von lpData 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 von lpData 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 nichtzero-Fehlercode, der in Winerror.h definiert ist. Sie können die FormatMessage-Funktion mit dem flag FORMAT_MESSAGE_FROM_SYSTEM verwenden, um eine generische Beschreibung des Fehlers abzurufen.
Wenn der lpData-Puffer zu klein ist, um den Wert zu empfangen, gibt die Funktion ERROR_MORE_DATA zurück.
Bemerkungen
Zum Auflisten von Werten sollte eine Anwendung zunächst die OREnumValue-Funktion aufrufen, wobei der dwIndex-Parameter auf 0 festgelegt ist. Die Anwendung sollte dann dwIndex inkrementieren und die OREnumValue-Funktion aufrufen, bis keine weiteren Werte vorhanden sind (bis die Funktion ERROR_NO_MORE_ITEMS zurückgibt).
Die Anwendung kann dwIndex auch auf den Index des letzten Werts beim ersten Aufruf der Funktion festlegen und den Index dekrementieren, bis der Wert mit Index 0 aufgezählt wird. Um den Index des letzten Werts abzurufen, verwenden Sie die FUNKTION ORQueryInfoKey .
Bei Verwendung von OREnumValue sollte eine Anwendung keine Offlineregistrierungsfunktionen aufrufen, die den abgefragten Schlüssel ändern könnten.
Wenn die Daten über den typ REG_SZ, REG_MULTI_SZ oder REG_EXPAND_SZ verfügen, wurde die Zeichenfolge möglicherweise nicht mit den richtigen NULL-Endzeichen gespeichert. Selbst wenn die Funktion ERROR_SUCCESS zurückgibt, sollte die Anwendung daher sicherstellen, dass die Zeichenfolge ordnungsgemäß beendet wird, bevor sie sie verwendet. Andernfalls kann ein Puffer überschrieben werden. (Beachten Sie, dass REG_MULTI_SZ Zeichenfolgen zwei NULL-Endzeichen aufweisen sollten.)
Verwenden Sie die Funktion ORQueryInfoKey , um die maximale Größe des Namens und der Datenpuffer zu bestimmen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Verteilbare Komponente |
Windows-Offlineregistrierungsbibliothek Version 1.0 oder höher |
| Header |
|
| DLL |
|
Siehe auch