IoReportResourceForDetection 函数 (ntddk.h)

  • 项目

IoReportResourceForDetection 例程声明旧设备的配置注册表中的硬件资源。

语法

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
);

参数

[in] DriverObject

指向输入到驱动程序的 DriverEntry 例程的驱动程序对象的指针。

[in, optional] DriverList

（可选）指向调用方提供的缓冲区，该缓冲区包含驱动程序的资源列表（如果驱动程序为其所有设备声明相同的资源）。 如果调用方指定 DeviceList，则忽略此参数。

[in, optional] DriverListSize

指定可选 DriverList 的大小（以字节为单位）。 如果 DriverList 为 NULL，则此参数应为零。

[in, optional] DeviceObject

（可选）指向表示驱动程序尝试声明资源的设备的设备对象。

[in, optional] DeviceList

（可选）指向包含设备资源列表的调用方提供的缓冲区。 如果驱动程序为其所有设备声明相同的资源，则调用方可以改为指定 DriverList 。

[in, optional] DeviceListSize

指定可选 DeviceList 的大小（以字节为单位）。 如果 DeviceList 为 NULL，则此参数应为零。

[out] ConflictDetected

指向调用方提供的布尔值的指针，如果资源不可用，该布尔值在返回时设置为 TRUE 。

返回值

如果声明了资源，IoReportResourceForDetection 将返回STATUS_SUCCESS。 可能的错误返回值包括以下内容。

返回代码 说明
STATUS_CONFLICTING_ADDRESSES 无法声明这些资源，因为它们已在使用中，或者 PnP 可枚举设备需要这些资源。
STATUS_UNSUCCESSFUL DeviceList 或 DriverList 无效。

注解

此例程适用于检测无法通过即插即用 (PnP) 枚举的早期硬件的驱动程序。

如果驱动程序仅支持 PnP 硬件，则不会进行检测，因此不调用 IoReportResourceForDetection。 PnP 系统枚举每个 PnP 设备，将资源分配给设备，并在 IRP_MN_START_DEVICE 请求中将这些资源传递给设备的驱动程序。

但是，如果 PnP 驱动程序支持旧硬件，则必须调用 IoReportResourceForDetection 来声明硬件资源，然后才能尝试检测设备。

此例程的调用方在 DeviceList 或 DriverList 中指定一个从分页内存中分配且由未转换的原始资源组成的CM_RESOURCE_LIST。 调用方负责释放内存。

可以同时控制多个旧卡的驱动程序应使用 DeviceObject、DeviceList 和 DeviceListSize 参数) 针对相应设备 (的设备对象声明每个设备的资源。 此类驱动程序不得对其驱动程序对象声明这些资源。

CM_RESOURCE_LIST包含两个大小可变的数组。 每个数组的默认大小为 1。 如果任一数组具有多个元素，调用方必须动态分配内存以包含其他元素。 列表中每个CM_FULL_RESOURCE_DESCRIPTOR只能有一个CM_PARTIAL_RESOURCE_DESCRIPTOR，CM_RESOURCE_LIST中最后一个完整资源描述符除外，该描述符的数组中可以包含其他部分资源描述符。

IoReportResourceForDetection 在 PnP 管理器的帮助下确定请求的资源是否与已声明的资源冲突。

如果检测到冲突，此例程将 ConflictDetected 处的 BOOLEAN 设置为 TRUE ，并返回STATUS_CONFLICTING_ADDRESSES。

如果未检测到冲突，此例程会声明资源，将 ConflictDetected 处的 BOOLEAN 设置为 FALSE，并返回STATUS_SUCCESS。

如果此例程成功，并且驱动程序检测到旧设备，驱动程序将通过调用 IoReportDetectedDevice 将设备报告给 PnP 管理器。 在该调用中，驱动程序将 ResourceAssigned 设置为 TRUE ，以便 PnP 管理器不会再次尝试声明资源。

当驱动程序不再需要调用此例程所声明的资源时，驱动程序会再次调用此例程的 DriverList 或 DeviceList （ 计数 为零）。

如果驱动程序为多个设备声明特定于设备的资源，则驱动程序必须为每个此类设备调用此例程。

驱动程序可以为给定设备多次调用此例程。 如果一组资源失败，驱动程序可以为具有不同资源集的同一设备再次调用例程。 如果一组资源成功，驱动程序可以使用新列表再次调用此例程;新列表将替换上一个列表。

IoReportResourceForDetection 的调用方必须在系统线程上下文中的 IRQL = PASSIVE_LEVEL 运行。

要求

要求 值
目标平台 通用
标头 ntddk.h (包括 Ntddk.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL (请参阅“备注”部分)

另请参阅

CM_RESOURCE_LIST

IoReportDetectedDevice