IO_SESSION_NOTIFICATION_FUNCTION回调函数 (wdm.h)

项目
02/27/2024

IO_SESSION_NOTIFICATION_FUNCTION函数类型定义回调例程，驱动程序通过该例程接收驱动程序感兴趣的用户会话状态更改通知。

语法

IO_SESSION_NOTIFICATION_FUNCTION IoSessionNotificationFunction;

NTSTATUS IoSessionNotificationFunction(
  [in] PVOID SessionObject,
  [in] PVOID IoObject,
  [in] ULONG Event,
  [in] PVOID Context,
  [in] PVOID NotificationPayload,
  [in] ULONG PayloadLength
)
{...}

参数

[in] SessionObject

指向包含用户会话相关信息的不透明系统对象的指针。驱动程序可以将此指针值作为 ContainerObject 参数值传递给 IoGetContainerInformation 例程。

[in] IoObject

指向驱动程序拥有的 I/O 对象的指针。此参数是驱动程序之前注册以接收会话事件通知时驱动程序提供给 IoRegisterContainerNotification 例程的 I/O 对象指针。 IoRegisterContainerNotification 例程的 NotificationInformation 参数指向其 IoObject 成员指向 I/O 对象的IO_SESSION_STATE_NOTIFICATION结构。

[in] Event

一个IO_SESSION_EVENT枚举常量，该常量指示哪个会话事件导致了通知回调。

[in] Context

驱动程序注册以接收会话事件通知时，驱动程序先前提供给 IoRegisterContainerNotification 例程的上下文值。在 IoRegisterContainerNotification 调用中，驱动程序提供了指向其 Context 成员包含上下文值的IO_SESSION_STATE_NOTIFICATION结构的指针。

[in] NotificationPayload

指向包含IO_SESSION_CONNECT_INFO结构的有效负载缓冲区的指针。

[in] PayloadLength

NotificationPayload 指向的缓冲区的大小（以字节为单位）。缓冲区大小永远不会超过 Wdm.h 头文件中定义的常量值IO_SESSION_MAX_PAYLOAD_SIZE。

返回值

如果例程成功，则必须返回STATUS_SUCCESS。否则，它必须返回 Ntstatus.h 头文件中定义的错误状态值之一。

注解

内核模式驱动程序实现此例程。 I/O 管理器调用此例程来通知驱动程序会话事件。

为了接收会话事件的通知，驱动程序调用 IoRegisterContainerNotification 例程，并将此例程的 CallbackFunction 参数设置为指向驱动程序IO_SESSION_NOTIFICATION_FUNCTION例程。驱动程序传递给 IoRegisterContainerNotification 的 I/O 对象确定驱动程序是接收特定用户会话中的事件的通知，还是接收所有会话中的事件的通知。有关详细信息，请参阅 IO_SESSION_STATE_NOTIFICATION。

示例

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

例如，若要定义名为 MyIoSessionNotification的 I/O 会话通知例程，请使用IO_SESSION_NOTIFICATION_FUNCTION类型，如以下代码示例所示：

IO_SESSION_NOTIFICATION_FUNCTION MyIoSessionNotification;

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

_Use_decl_annotations_
NTSTATUS
  MyIoSessionNotification(
    PVOID  SessionObject,
    PVOID  IoObject,
    ULONG  Event,
    PVOID  Context,
    PVOID  NotificationPayload,
    ULONG  PayloadLength
    )
  {
      // Function body
  }

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

要求

要求	值
最低受支持的客户端	在 Windows 7 及更高版本的 Windows 操作系统中受支持。
目标平台	桌面
标头	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h、Fltkernel.h)
IRQL	在 IRQL <= APC_LEVEL 调用。