Funzione ZwEnumerateKey (wdm.h)

Articolo
02/27/2024

La routine ZwEnumerateKey restituisce informazioni su una sottochiave di una chiave del Registro di sistema aperta.

Sintassi

NTSYSAPI NTSTATUS ZwEnumerateKey(
  [in]            HANDLE                KeyHandle,
  [in]            ULONG                 Index,
  [in]            KEY_INFORMATION_CLASS KeyInformationClass,
  [out, optional] PVOID                 KeyInformation,
  [in]            ULONG                 Length,
  [out]           PULONG                ResultLength
);

Parametri

[in] KeyHandle

Handle per la chiave del Registro di sistema che contiene le sottochiavi da enumerare. L'handle viene creato da una chiamata riuscita a ZwCreateKey o ZwOpenKey.

[in] Index

Indice della sottochiave per cui si desidera ottenere informazioni. Se la chiave contiene n sottochiavi, le sottochiavi vengono numerate da 0 a n-1.

[in] KeyInformationClass

Specifica un valore di enumerazione KEY_INFORMATION_CLASS che determina il tipo di informazioni da ricevere dal buffer KeyInformation . Impostare KeyInformationClass su uno dei valori seguenti:

KeyBasicInformation
KeyFullInformation
KeyNodeInformation

Se viene specificato un valore diverso da questo elenco, la routine restituisce il codice di errore STATUS_INVALID_PARAMETER.

[out, optional] KeyInformation

Puntatore a un buffer allocato dal chiamante che riceve le informazioni richieste. Il parametro KeyInformationClass determina il tipo di informazioni fornite.

[in] Length

Specifica le dimensioni, in byte, del buffer KeyInformation .

[out] ResultLength

Puntatore a una variabile che riceve le dimensioni, in byte, delle informazioni sulla chiave del Registro di sistema. Se ZwEnumerateKey restituisce STATUS_SUCCESS, è possibile usare il valore di questa variabile per determinare la quantità di dati restituiti. Se la routine restituisce STATUS_BUFFER_OVERFLOW o STATUS_BUFFER_TOO_SMALL, è possibile utilizzare il valore di questa variabile per determinare le dimensioni del buffer necessarie per contenere le informazioni sulla chiave.

Valore restituito

ZwEnumerateKey restituisce STATUS_SUCCESS in caso di esito positivo o il codice di errore NTSTATUS appropriato in caso di errore. I valori possibili del codice di errore includono:

Codice restituito	Descrizione
STATUS_BUFFER_OVERFLOW	Il buffer fornito è troppo piccolo e solo i dati parziali sono stati scritti nel buffer. *ResultLength è impostato sulle dimensioni minime necessarie per contenere le informazioni richieste.
STATUS_BUFFER_TOO_SMALL	Il buffer fornito è troppo piccolo e non sono stati scritti dati nel buffer. *ResultLength è impostato sulle dimensioni minime necessarie per contenere le informazioni richieste.
STATUS_INVALID_PARAMETER	Il parametro KeyInformationClass non è un valore di KEY_INFORMATION_CLASS valido.
STATUS_NO_MORE_ENTRIES	Il valore index non è compreso nell'intervallo per la chiave del Registro di sistema specificata da KeyHandle. Ad esempio, se una chiave ha n sottochiavi, per qualsiasi valore maggiore di n-1 la routine restituisce STATUS_NO_MORE_ENTRIES.

Commenti

L'handle deve essere stato aperto con accesso KEY_ENUMERATE_SUB_KEYS. A tale scopo, passare KEY_ENUMERATE_SUB_KEYS, KEY_READ o KEY_ALL_ACCESS come parametro DesiredAccess a ZwCreateKey o ZwOpenKey.

Il parametro Index è semplicemente un modo per selezionare tra sottochiavi della chiave a cui fa riferimento KeyHandle. Non è garantito che due chiamate a ZwEnumerateKey con lo stesso indice restituiscano lo stesso risultato.

Per altre informazioni sull'uso delle chiavi del Registro di sistema, vedere Uso del Registro di sistema in un driver.

Se la chiamata a questa funzione si verifica in modalità utente, è necessario usare il nome "NtEnumerateKey" anziché "ZwEnumerateKey".

Per le chiamate da driver in modalità kernel, le versioni NtXxx e ZwXxx di una routine di Servizi di sistema nativi di Windows possono comportarsi in modo diverso nel modo in cui gestiscono e interpretano i parametri di input. Per altre informazioni sulla relazione tra le versioni NtXxx e ZwXxx di una routine, vedere Using Nt and Zw Versions of the Native System Services Routines .For more information about the Nt Xxx and Zw versions of the Native System Services Routines.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(storport), ZwRegistryOpen(storport), ZwRegistryOpen(wdm)