Función IoReportResourceForDetection (ntddk.h)

La rutina IoReportResourceForDetection reclama recursos de hardware en el registro de configuración de un dispositivo heredado.

Sintaxis

NTSTATUS IoReportResourceForDetection(
  [in]           PDRIVER_OBJECT    DriverObject,
  [in, optional] PCM_RESOURCE_LIST DriverList,
  [in, optional] ULONG             DriverListSize,
  [in, optional] PDEVICE_OBJECT    DeviceObject,
  [in, optional] PCM_RESOURCE_LIST DeviceList,
  [in, optional] ULONG             DeviceListSize,
  [out]          PBOOLEAN          ConflictDetected
);

Parámetros

[in] DriverObject

Puntero al objeto de controlador que se ha introducido en la rutina DriverEntry del controlador.

[in, optional] DriverList

Opcionalmente, apunta a un búfer proporcionado por el autor de la llamada que contiene la lista de recursos del controlador, si el controlador reclama los mismos recursos para todos sus dispositivos. Si el autor de la llamada especifica deviceList, este parámetro se omite.

[in, optional] DriverListSize

Especifica el tamaño en bytes de un DriverList opcional. Si DriverList es NULL, este parámetro debe ser cero.

[in, optional] DeviceObject

Opcionalmente, apunta al objeto de dispositivo que representa el dispositivo para el que el controlador está intentando reclamar recursos.

[in, optional] DeviceList

Opcionalmente, apunta a un búfer proporcionado por el autor de la llamada que contiene la lista de recursos del dispositivo. Si el controlador reclama los mismos recursos para todos sus dispositivos, el autor de la llamada puede especificar un driverList en su lugar.

[in, optional] DeviceListSize

Especifica el tamaño en bytes de un DeviceList opcional. Si DeviceList es NULL, este parámetro debe ser cero.

[out] ConflictDetected

Puntero a un valor booleano proporcionado por el autor de la llamada que se establece en TRUE si los recursos no están disponibles.

Valor devuelto

IoReportResourceForDetection devuelve STATUS_SUCCESS si se reclaman los recursos. Entre los valores devueltos de error posibles se incluyen los siguientes.

Código devuelto	Descripción
STATUS_CONFLICTING_ADDRESSES	No se pudieron reclamar los recursos porque ya están en uso o son necesarios para un dispositivo enumerable PnP.
STATUS_UNSUCCESSFUL	DeviceList o DriverList no son válidos.

Comentarios

Esta rutina es para los controladores que detectan hardware anterior que no se puede enumerar mediante Plug and Play (PnP).

Si un controlador solo admite hardware PnP, no realiza ninguna detección y, por tanto, no llama a IoReportResourceForDetection. El sistema PnP enumera cada dispositivo PnP, asigna recursos al dispositivo y pasa esos recursos a los controladores del dispositivo en una solicitud de IRP_MN_START_DEVICE .

Sin embargo, si un controlador PnP admite hardware heredado, debe llamar a IoReportResourceForDetection para reclamar recursos de hardware antes de intentar detectar el dispositivo.

Los autores de llamadas de esta rutina especifican un CM_RESOURCE_LIST en deviceList o driverList que se asigna desde la memoria paginada y que consta de recursos sin procesar y sin traducir. El autor de la llamada es responsable de liberar la memoria.

Un controlador que pueda controlar más de una tarjeta heredada al mismo tiempo debe reclamar los recursos de cada dispositivo en el objeto de dispositivo correspondiente (mediante los parámetros DeviceObject, DeviceList y DeviceListSize ). Este controlador no debe reclamar estos recursos contra su objeto de controlador.

Un CM_RESOURCE_LIST contiene dos matrices de tamaño variable. Cada matriz tiene un tamaño predeterminado de uno. Si alguna matriz tiene más de un elemento, el autor de la llamada debe asignar memoria dinámicamente para contener los elementos adicionales. Solo una CM_PARTIAL_RESOURCE_DESCRIPTOR puede formar parte de cada CM_FULL_RESOURCE_DESCRIPTOR de la lista, excepto el último descriptor de recursos completo de la CM_RESOURCE_LIST, que puede tener descriptores de recursos parciales adicionales en su matriz.

IoReportResourceForDetection, con la ayuda del administrador de PnP, determina si los recursos que se solicitan entran en conflicto con los recursos que ya se han reclamado.

Si se detecta un conflicto, esta rutina establece el valor BOOLEAN en ConflictDetected enTRUE y devuelve STATUS_CONFLICTING_ADDRESSES.

Si no se detecta ningún conflicto, esta rutina reclama los recursos, establece el valor BOOLEAN en ConflictDetected enFALSE y devuelve STATUS_SUCCESS.

Si esta rutina se realiza correctamente y el controlador detecta un dispositivo heredado, el controlador notifica el dispositivo al administrador de PnP mediante una llamada a IoReportDetectedDevice. En esa llamada, el controlador establece ResourceAssigned enTRUE para que el administrador de PnP no intente volver a reclamar los recursos.

Cuando un controlador ya no requiere los recursos reclamados por una llamada a esta rutina, el controlador vuelve a llamar a esta rutina con un DriverList o DeviceList con un recuento de cero.

Si un controlador reclama recursos específicos de un dispositivo para más de un dispositivo, el controlador debe llamar a esta rutina para cada dispositivo de este tipo.

Un controlador puede llamar a esta rutina más de una vez para un dispositivo determinado. Si se produce un error en un conjunto de recursos, el controlador puede llamar de nuevo a la rutina para el mismo dispositivo con un conjunto diferente de recursos. Si un conjunto de recursos se realiza correctamente, el controlador puede llamar a esta rutina de nuevo con una nueva lista; la nueva lista reemplaza a la lista anterior.

Los autores de llamadas de IoReportResourceForDetection deben ejecutarse en IRQL = PASSIVE_LEVEL en el contexto de un subproceso del sistema.

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	ntddk.h (incluya Ntddk.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte la sección Comentarios)

Consulte también

CM_RESOURCE_LIST

IoReportDetectedDevice