Función IoEnumerateDeviceObjectList (ntifs.h)
La rutina IoEnumerateDeviceObjectList enumera la lista de objetos de dispositivo de un controlador.
Sintaxis
NTSTATUS IoEnumerateDeviceObjectList(
[in] PDRIVER_OBJECT DriverObject,
[out] PDEVICE_OBJECT *DeviceObjectList,
[in] ULONG DeviceObjectListSize,
[out] PULONG ActualNumberDeviceObjects
);
Parámetros
[in] DriverObject
Puntero al objeto de controlador para el controlador.
[out] DeviceObjectList
Puntero a una matriz asignada por el autor de la llamada que recibe los punteros del objeto de dispositivo. Esta matriz debe asignarse desde un grupo no paginado. Este parámetro puede ser NULL. Vea comentarios.
[in] DeviceObjectListSize
Tamaño, en bytes, de la matriz de DeviceObjectList. Este parámetro puede ser cero. Vea comentarios.
[out] ActualNumberDeviceObjects
Número real de objetos de dispositivo encontrados en la lista de objetos de dispositivo del objeto de controlador. Tenga en cuenta que si la matriz de DeviceObjectList es demasiado pequeña, el número de punteros de objeto de dispositivo que se copian en la matriz será menor que ActualNumberDeviceObjects.
Valor devuelto
IoEnumerateDeviceObjectList devuelve un código NTSTATUS, como uno de los siguientes valores:
| Código devuelto | Descripción |
|---|---|
| STATUS_SUCCESS | La llamada a IoEnumerateDeviceObjectList se completó correctamente. |
| STATUS_BUFFER_TOO_SMALL | La matriz de DeviceObjectList es demasiado pequeña para contener toda la lista de objetos de dispositivo. En este caso, IoEnumerateDeviceObjectList copia tantos punteros de objeto de dispositivo en la matriz como sea posible. |
Observaciones
Un controlador de filtro del sistema de archivos llama a IoEnumerateDeviceObjectList para enumerar:
Los objetos de dispositivo que ha creado. Esto suele hacerse cuando el controlador se prepara para descargar. Tenga en cuenta que un controlador de filtro no se puede descargar de forma segura desde un sistema en ejecución. Para obtener más información, vea ZwUnloadDriver.
Los objetos de dispositivo creados por el sistema de archivos base, por lo que el filtro conoce el número de volúmenes a los que se puede adjuntar.
ioEnumerateDeviceObjectList devuelve todos los objetos de dispositivo creados por el controlador de filtro. Esto incluye objetos de dispositivo de control (DPO), así como objetos de dispositivo de volumen (VDOs). Los dos tipos de objetos de dispositivo se pueden distinguir por el hecho de que, por convención, los CDO se denominan y los VDOs no.
En este último caso, el controlador de filtro normalmente llama a IoEnumerateDeviceObjectList dos veces: una vez para obtener el número de objetos de dispositivo de la lista y una vez para obtener la lista de objetos de dispositivo. En la primera llamada, el llamador debe establecer el parámetro DeviceObjectList en NULL y DeviceObjectListSize en cero. En la segunda llamada, DeviceObjectList debe contener un puntero a una matriz de punteros de tamaño adecuado y DeviceObjectListSize debe contener el tamaño, en bytes, de esa matriz.
IoEnumerateDeviceObjectList incrementa el recuento de referencias en todos los objetos de dispositivo de la lista a los que apunta DeviceObjectList. Por lo tanto, todas las llamadas correctas a IoEnumerateDeviceObjectList deben coincidir con una llamada posterior a ObDereferenceObject para cada objeto de dispositivo de la lista. Si no lo hace, se impide que el sistema libere o elimine estos objetos de dispositivo debido a un recuento de referencias pendiente.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Paquete acumulativo de actualizaciones de Windows 2000 SP4; Windows XP |
| de la plataforma de destino de | Universal |
| encabezado de | ntifs.h (incluya Ntifs.h) |
| biblioteca de | NtosKrnl.lib |
| DLL de | NtosKrnl.exe |
| irQL | <= DISPATCH_LEVEL |