IoRegisterContainerNotification 函数 (wdm.h)

  • 项目

IoRegisterContainerNotification 例程注册内核模式驱动程序，以接收有关指定事件类的通知。

语法

NTSTATUS
IoRegisterContainerNotification(
    _In_ IO_CONTAINER_NOTIFICATION_CLASS NotificationClass,
    _In_ PIO_CONTAINER_NOTIFICATION_FUNCTION CallbackFunction,
    _In_reads_bytes_opt_(NotificationInformationLength) PVOID NotificationInformation,
    _In_ ULONG NotificationInformationLength,
    _Out_ PVOID * CallbackRegistration
    );

参数

[in] NotificationClass

指定调用方 (驱动程序) 请求通知的事件类。 将此参数设置为以下 IO_CONTAINER_NOTIFICATION_CLASS 枚举值：

  • IoSessionStateNotification

有关更多信息，请参见下面的“备注”部分。

[in] CallbackFunction

指向由调用方 (驱动程序) 实现的回调函数的指针。 I/O 管理器调用此函数，以便在发生 由 NotificationClass 指示的类的事件时通知调用方。 对于 NotificationClass = IoSessionStateNotification，此参数是指向调用方提供的 IO_SESSION_NOTIFICATION_FUNCTION 函数的指针。 但是，调用方应将此函数指针强制转换为类型PIO_CONTAINER_NOTIFICATION_FUNCTION以匹配参数类型。 有关更多信息，请参见下面的“备注”部分。

[in, optional] NotificationInformation

指向调用方分配的缓冲区的指针，该缓冲区包含 由 NotificationClass 指定的类的事件的通知信息结构。 对于 NotificationClass = IoSessionStateNotification，NotificationInformation 指向IO_SESSION_STATE_NOTIFICATION结构。 调用方必须先填写此结构，然后才能调用 IoRegisterContainerNotification。 在此调用期间， IoRegisterContainerNotification 从此结构复制数据，并且 I/O 管理器在调用返回后不会访问该结构的驱动程序副本。

[in] NotificationInformationLength

NotificationInformation 指向的缓冲区中包含的通知信息结构的大小（以字节为单位）。 对于 NotificationClass = IoSessionStateNotification，请将此参数设置为 sizeof (IO_SESSION_STATE_NOTIFICATION) 。

[out] CallbackRegistration

指向此例程在其中写入容器通知注册对象的地址的位置的指针。 此对象是一个不透明的系统对象，I/O 管理器在其中存储有关调用方容器通知注册的信息。 不再需要通知时，调用方通过将此对象指针传递到 IoUnregisterContainerNotification 例程来取消注册。

返回值

如果调用成功，IoRegisterContainerNotification 将返回STATUS_SUCCESS。 可能的错误返回值包括以下内容：

返回代码 说明
STATUS_INVALID_PARAMETER_1 参数 NotificationClass 不是有效的 IO_CONTAINER_NOTIFICATION_CLASS 枚举常量。
STATUS_INVALID_PARAMETER_3 由 NotificationInformation 指向的结构中的信息不正确。
STATUS_INVALID_PARAMETER_4 参数 NotificationInformationLength 不等于与指定的 NotificationClass 参数值一起使用所需的通知信息结构的大小。
STATUS_ALREADY_COMMITTED 驱动程序已注册以接收与指定 I/O 对象关联的事件的 NotificationClass 通知。
STATUS_INSUFFICIENT_RESOURCES 操作系统没有足够的资源来创建请求的注册。

注解

此例程可能支持各种事件类中的事件通知。 在 Windows 7 中，此例程仅支持 IoSessionStateNotification 通知，这些通知内核模式驱动程序有关驱动程序感兴趣的用户会话状态的更改。 对于用户模式应用程序， WTSRegisterSessionNotification 函数将填充类似的角色。

CallbackFunction 参数的函数指针类型定义如下：

typedef NTSTATUS
  (*PIO_CONTAINER_NOTIFICATION_FUNCTION)(
    );

调用方应将回调函数指针强制转换为此类型，以匹配 CallbackFunction 参数类型。 IoRegisterContainerNotification 通过 NotificationClass 参数确定回调函数指针的实际类型。 对于 NotificationClass = IoSessionStateNotification，CallbackFunction 指向IO_SESSION_NOTIFICATION_FUNCTION函数。

要求

要求 值
最低受支持的客户端 适用于 Windows 7 及更高版本的 Windows 操作系统。
目标平台 通用
标头 wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h、Fltkernel.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= APC_LEVEL

另请参阅

IO_CONTAINER_NOTIFICATION_CLASS

IO_SESSION_NOTIFICATION_FUNCTION

IO_SESSION_STATE_NOTIFICATION

IoUnregisterContainerNotification

WTSRegisterSessionNotification