DRIVER_CONTROL回调函数 (wdm.h)

  • 项目

此例程启动 DMA 数据传输或数据传输操作。

语法

DRIVER_CONTROL DriverControl;

IO_ALLOCATION_ACTION DriverControl(
  [in]      _DEVICE_OBJECT *DeviceObject,
  [in, out] _IRP *Irp,
  [in]      PVOID MapRegisterBase,
  [in]      PVOID Context
)
{...}

参数

[in] DeviceObject

调用方提供的指向 DEVICE_OBJECT 结构的指针。 这是目标设备的设备对象，以前由驱动程序的 AddDevice 例程创建。

[in, out] Irp

调用方提供的指向 IRP 结构的指针。 Irp 等于注册回调例程时 DeviceObject 的 CurrentIrp 成员的值。

[in] MapRegisterBase

对于 AdapterControl，这是调用方提供的不透明值，表示系统为此传输操作分配的映射寄存器。 驱动程序将此值传递给 FlushAdapterBuffers、 FreeMapRegisters 和 MapTransfer。

对于 ControllerControl，不使用此选项。

[in] Context

调用方提供的指向驱动程序定义的上下文信息的指针，在上一次 对 AllocateAdapterChannel 的调用中指定。

返回值

例程必须返回 IO_ALLOCATION_ACTION 枚举定义的值之一。 总线主设备的驱动程序返回 DeallocateObject 或 DeallocateObjectKeepRegisters;使用系统 DMA 的驱动程序返回 KeepObject。

注解

若要为特定设备对象注册 AdapterControl 例程，驱动程序必须调用 IoGetDmaAdapter 以获取适配器对象，然后调用 AllocateAdapterChannel 以请求使用适配器并提供 AdapterControl 例程的地址。 适配器可用时，系统会调用 AdapterControl 例程。

如果 AdapterControl 已由 StartIo 例程注册，则 Irp 参数保证指向 StartIo 例程当前正在处理的 IRP。 否则，驱动程序必须在调用 AllocateAdapterChannel 之前设置设备对象结构的 CurrentIrp 成员。

有关实现 AdapterControl 例程的详细信息，请参阅 编写 AdapterControl 例程。

驱动程序的 ControllerControl 例程在 IRQL = DISPATCH_LEVEL 的任意线程上下文中执行。

若要为特定设备对象注册 ControllerControl 例程，驱动程序必须调用 IoCreateController 以获取控制器对象，然后调用 IoAllocateController 以请求使用控制器并提供 ControllerControl 例程的地址。 当控制器可用时，系统会调用 ControllerControl 例程。

有关实现 ControllerControl 例程的详细信息，请参阅 编写 ControllerControl 例程。 另请参阅 控制器对象。

DRIVER_CONTROL函数类型在 Wdm.h 头文件中定义。 若要在运行代码分析工具时更准确地识别错误，请务必将 _Use_decl_annotations_ 注释添加到函数定义。 注释 _Use_decl_annotations_ 可确保使用应用于头文件中DRIVER_CONTROL函数类型的注释。 有关函数声明要求的详细信息，请参阅 使用 WDM 驱动程序的函数角色类型声明函数。 有关 的信息 _Use_decl_annotations_，请参阅 批注函数行为。

示例

若要定义回调例程，必须先提供一个函数声明，用于标识要定义的回调例程的类型。 Windows 为驱动程序提供了一组回调函数类型。 使用回调函数类型声明函数可帮助 驱动程序的代码分析、 静态驱动程序验证程序 (SDV) 和其他验证工具查找错误，这是为 Windows 操作系统编写驱动程序的要求。

例如，若要定义名为 MyAdapterControl的 AdapterControl 回调例程，请使用 DRIVER_CONTROL 类型，如以下代码示例所示：

DRIVER_CONTROL MyAdapterControl;

然后，按如下所示实现回调例程：

_Use_decl_annotations_
IO_ALLOCATION_ACTION
 MyAdapterControl(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp,
    PVOID  MapRegisterBase,
    PVOID  Context
    )
  {
      // Function body
  }

要求

要求 值
目标平台 桌面
标头 wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
IRQL 在 DISPATCH_LEVEL 调用。

另请参阅

AllocateAdapterChannel