PFNKSHANDLER 回调函数 (ks.h)

项目
02/26/2024

当内核流收到 IOCTL_KS_METHOD get/set 属性请求时，将调用微型驱动程序提供的例程。在相关 KSMETHOD_ITEM KSPROPERTY_ITEM结构中提供指向此处理程序的指针。

语法

PFNKSHANDLER Pfnkshandler;

NTSTATUS Pfnkshandler(
  [in]      PIRP Irp,
  [in]      PKSIDENTIFIER Request,
  [in, out] PVOID Data
)
{...}

参数

[in] Irp

指定包含方法或属性请求的 IRP。

[in] Request

指定方法参数的对齐副本。这通常是指向 KSMETHOD 或 KSPROPERTY 结构的指针。

[in, out] Data

指定方法数据参数或原始数据参数的系统地址的对齐副本，具体取决于方法 KSMETHOD_ITEM 结构中指定的标志。

返回值

如果方法已处理，并且已根据 KSMETHOD_ITEM 中指定的标志填充数据缓冲区，则返回STATUS_SUCCESS。如果返回数据，驱动程序应设置 Irp-IoStatus.Information> 字段，但不应设置 Irp-IoStatus.Status> 字段，也不应完成 IRP。如果要异步完成，请将 IRP 标记为挂起。

或者，如果方法已处理，但特定请求尚未完成，并且必须由调用帮助程序函数完成，则返回STATUS_SOME_NOT_MAPPED。返回任何其他错误消息，指示方法不受支持或发生了参数错误。

注解

微型驱动程序在 KSMETHOD_ITEM 结构的 MethodHandler 成员中指定此例程的地址。

用于 KStrMethodHandler 和 KStrSupportHandler 的处理程序声明也用于属性和事件集的处理程序，具有相同的参数和返回值。

当帮助程序函数（如 KsMethodHandler）调用其数据缓冲区定义为写入或修改缓冲区的方法处理程序时，方法处理程序必须将 IRP (Irp 参数中 IoStatus 成员的 IO_STATUS_BLOCK 结构的 Information 成员) 设置为该数据缓冲区的大小。微型驱动程序将方法KSMETHOD_ITEM结构的 Flags 成员设置为KSMETHOD_TYPE_WRITE或KSMETHOD_TYPE_MODIFY分别将方法处理程序的数据缓冲区定义为写入或修改。

以下代码片段演示方法处理程序的实现示例，该方法处理程序在 IRP 中设置返回的数据缓冲区的大小：

NTSTATUS
  MethodHandler(PIRP pIrp, PKSIDENTIFIER Request, PVOID Data) {
    NTSTATUS Status = STATUS_UNSUCCESSFUL;
    // Pointer to hold the position on the Irp stack
    PIO_STACK_LOCATION  pIrpStack  = NULL;
    ASSERT(pIrp);
    if(Data) {
        // Modify data here
    }
    // Find the current Irp stack.
    pIrpStack = IoGetCurrentIrpStackLocation(pIrp);
    if(pIrpStack) {
        // Set the size of the returning Irp data.
        pIrp->IoStatus.Information =
          pIrpStack->Parameters.DeviceIoControl.OutputBufferLength;
        Status = STATUS_SUCCESS;
    }
    return(Status);
}

微型驱动程序在 KSPROPERTY_ITEM 结构的 GetPropertyHandler 成员中指定此例程的地址。

微型驱动程序在 KSPROPERTY_ITEM 结构的 SetPropertyHandler 成员中指定此例程的地址。

微型驱动程序在 KSMETHOD_ITEM 结构的 SupportHandler 成员中指定此例程的地址。

用于 KStrMethodHandler 和 KStrSupportHandler 的处理程序声明也用于属性和事件集的处理程序，具有相同的参数和返回值。