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 de objeto de dispositivo. Esta matriz debe asignarse desde un grupo no paginado. Este parámetro puede ser NULL. Vea la sección Comentarios.
[in] DeviceObjectListSize
Tamaño, en bytes, de la matriz DeviceObjectList . Este parámetro puede ser cero. Vea la sección Comentarios.
[out] ActualNumberDeviceObjects
Número real de objetos de dispositivo que se encuentran 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 objetos de dispositivo en la matriz como sea posible. |
Comentarios
Un controlador de filtro del sistema de archivos llama a IoEnumerateDeviceObjectList para enumerar:
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 puede adjuntarse.
IoEnumerateDeviceObjectList devuelve todos los objetos de dispositivo creados por el controlador de filtro. Esto incluye objetos de dispositivo de control (CDO), así como objetos de dispositivo de volumen (VDO). 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 propia 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 cada objeto de dispositivo de la lista a la que apunta DeviceObjectList. Por lo tanto, cada llamada correcta a IoEnumerateDeviceObjectList debe 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 | Value |
|---|---|
| Cliente mínimo compatible | Paquete acumulativo de actualizaciones de Windows 2000 SP4; Windows XP |
| Plataforma de destino | Universal |
| Encabezado | ntifs.h (incluya Ntifs.h) |
| Library | NtosKrnl.lib |
| Archivo DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL |