IoEnumerateDeviceObjectList-Funktion (ntifs.h)
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 seitengebundenen Pool zugewiesen werden. Dieser Parameter kann NULL sein. Siehe Anmerkungen.
[in] DeviceObjectListSize
Größe des DeviceObjectList- Arrays in Byte. Dieser Parameter kann null sein. Siehe Anmerkungen.
[out] ActualNumberDeviceObjects
Die tatsächliche Anzahl der Geräteobjekte, die in der Geräteobjektliste des Treiberobjekts gefunden wurden. Wenn das Array bei DeviceObjectList- zu klein ist, ist die Anzahl der In das Array kopierten Geräteobjektzeiger kleiner als ActualNumberDeviceObjects.
Rückgabewert
IoEnumerateDeviceObjectList gibt einen NTSTATUS-Code wie einen der folgenden Werte zurück:
| Rückgabecode | Beschreibung |
|---|---|
| STATUS_SUCCESS | Der Aufruf von IoEnumerateDeviceObjectList erfolgreich abgeschlossen. |
| STATUS_BUFFER_TOO_SMALL | Das Array bei DeviceObjectList- ist zu klein, um die gesamte Geräteobjektliste zu speichern. In diesem Fall kopiert IoEnumerateDeviceObjectList so viele Geräteobjektzeiger wie möglich in das Array. |
Bemerkungen
Ein Dateisystemfiltertreiber ruft IoEnumerateDeviceObjectList auf, um aufgezählt zu werden:
Die erstellten Geräteobjekte. Dies geschieht häufig, wenn sich der Treiber auf das Entladen 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 alle Geräteobjekte zurück, die vom Filtertreiber erstellt wurden. Dazu gehören Steuergeräteobjekte (CONTROL Device Objects, CDOs) sowie Volumegeräteobjekte (VOLUME Device Objects, VDOs). Die beiden Arten von Geräteobjekten können durch die Tatsache unterschieden werden, dass CDOs nach Konvention benannt sind und VDOs nicht.
Im letzteren Fall ruft der Filtertreiber in der Regel IoEnumerateDeviceObjectList 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 festlegen und DeviceObjectListSize auf Null festlegen. Im zweiten Aufruf sollte DeviceObjectList- einen Zeiger auf ein entsprechend großes Zeigerarray enthalten, und DeviceObjectListSize die Größe in Byte dieses Arrays enthalten soll.
IoEnumerateDeviceObjectList erhöht die Verweisanzahl für jedes Geräteobjekt in der Liste, auf das DeviceObjectListverweist. 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 ausstehenden Verweisanzahl freigibt oder löscht.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 2000 SP4 Update Rollup; Windows XP |
| Zielplattform- | Universal |
| Header- | ntifs.h (einschließlich Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | <= DISPATCH_LEVEL |