IoEnumerateDeviceObjectList-Funktion (ntifs.h)

Artikel
03/08/2023

Die IoEnumerateDeviceObjectList-Routine listet die Geräteobjektliste eines Treibers auf.

Syntax

NTSTATUS IoEnumerateDeviceObjectList(
  [in]  PDRIVER_OBJECT DriverObject,
  [out] PDEVICE_OBJECT *DeviceObjectList,
  [in]  ULONG          DeviceObjectListSize,
  [out] PULONG         ActualNumberDeviceObjects
);

Parameter

[in] DriverObject

Ein Zeiger auf das Treiberobjekt für den Treiber.

[out] DeviceObjectList

Ein Zeiger auf ein vom Aufrufer zugewiesenes Array, das die Geräteobjektzeiger empfängt. Dieses Array muss aus einem nicht ausgestellten Pool zugeordnet werden. Dieser Parameter kann NULL sein. Siehe Hinweise.

[in] DeviceObjectListSize

Größe des DeviceObjectList-Arrays in Bytes. Dieser Parameter kann 0 sein. Siehe Hinweise.

[out] ActualNumberDeviceObjects

Die tatsächliche Anzahl der Geräteobjekte, die in der Geräteobjektliste des Treiberobjekts gefunden wurden. Beachten Sie, dass die Anzahl der Geräteobjektzeiger, die in das Array kopiert werden, kleiner als ActualNumberDeviceObjects ist, wenn das Array bei DeviceObjectList zu klein ist.

Rückgabewert

IoEnumerateDeviceObjectList gibt einen NTSTATUS-Code wie einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Der Aufruf von IoEnumerateDeviceObjectList wurde erfolgreich abgeschlossen.
STATUS_BUFFER_TOO_SMALL	Das Array bei DeviceObjectList ist zu klein, um die gesamte Geräteobjektliste aufzunehmen. In diesem Fall kopiert IoEnumerateDeviceObjectList so viele Geräteobjektzeiger wie möglich in das Array.

Hinweise

Ein Dateisystemfiltertreiber ruft IoEnumerateDeviceObjectList auf, um aufzulisten:

Die Geräteobjekte, die erstellt wurden. Dies geschieht in der Regel, wenn der Treiber die Entladung vorbereitet. Beachten Sie, dass ein Filtertreiber nicht sicher aus einem ausgeführten System entladen werden kann. Weitere Informationen finden Sie unter ZwUnloadDriver.
Die vom Basisdateisystem erstellten Geräteobjekte, sodass der Filter die Anzahl der Volumes kennt, an die er anfügen kann.

IoEnumerateDeviceObjectList gibt alle Geräteobjekte zurück, die vom Filtertreiber erstellt wurden. Dies umfasst Steuergeräteobjekte (CDOs) sowie Volumegeräteobjekte (VDOs). Die beiden Arten von Geräteobjekten können dadurch unterschieden werden, dass CDOs gemäß Konvention benannt werden und VDOs nicht.

Im letzteren Fall ruft der Filtertreiber IoEnumerateDeviceObjectList in der Regel zweimal auf: einmal, um die Anzahl der Geräteobjekte in der Liste abzurufen, und einmal, um die Geräteobjektliste selbst abzurufen. Im ersten Aufruf sollte der Aufrufer den DeviceObjectList-Parameter auf NULL und DeviceObjectListSize auf Null festlegen. Im zweiten Aufruf sollte DeviceObjectList einen Zeiger auf ein Zeigerarray mit entsprechender Größe enthalten, und DeviceObjectListSize sollte die Größe dieses Arrays in Bytes enthalten.

IoEnumerateDeviceObjectList erhöht die Verweisanzahl für jedes Geräteobjekt in der Liste, auf die von DeviceObjectList verwiesen wird. Daher muss jeder erfolgreiche Aufruf von IoEnumerateDeviceObjectList durch einen nachfolgenden Aufruf von ObDereferenceObject für jedes Geräteobjekt in der Liste abgeglichen werden. Andernfalls wird verhindert, dass das System diese Geräteobjekte aufgrund einer hervorragenden Referenzanzahl freigibt oder löscht.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 SP4-Updaterollup; Windows XP
Zielplattform	Universell
Header	ntifs.h (include Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL