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

不透明系統物件的指標，其中包含用戶會話的相關信息。驅動程式可以將這個指標值傳遞至 IoGetContainerInformation 例程作為 ContainerObject 參數值。

[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 所指向緩衝區的大小，以位元組為單位。緩衝區大小絕對不需要超過常數值IO_SESSION_MAX_PAYLOAD_SIZE，這是在 Wdm.h 頭檔中定義的。

傳回值

如果例程成功，它必須傳回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呼叫。