KDEFERRED_ROUTINE回呼函式 (wdm.h)

發行項
02/29/2024

回呼例程會在 Threaded DPC 的 InterruptService 傳回之後，執行動作。

CustomDpc 例程會在 InterruptService 例程傳回之後，完成 I/O 作業的服務。

CustomThreadedDpc 例程會執行線程 DPC 的動作。當線程 DPC 執行時，系統會執行此例程。

CustomTimerDpc 例程會在定時器對象的時間間隔到期之後執行。

語法

KDEFERRED_ROUTINE KdeferredRoutine;

void KdeferredRoutine(
  [in]           _KDPC *Dpc,
  [in, optional] PVOID DeferredContext,
  [in, optional] PVOID SystemArgument1,
  [in, optional] PVOID SystemArgument2
)
{...}

參數

[in] Dpc

KDPC 結構的呼叫端提供指標，代表與此回呼例程相關聯的 DPC 物件。

[in, optional] DeferredContext

針對 CustomDpc，呼叫端提供的指標指向先前呼叫 KeInitializeDpc 中所指定的驅動程式定義內容資訊。

針對 CustomThreadedDpc，指定驅動程式定義的內容資訊。初始化 DPC 物件時，驅動程式會將此值當做 DeferredContext 參數提供給 KeInitializeThreadedDpc。

KDPC 結構的呼叫端提供指標，代表與此 CustomTimerDpc 例程相關聯的 DPC 物件。

[in, optional] SystemArgument1

呼叫端提供的指標，指向先前呼叫 KeInsertQueueDpc 中指定的驅動程式提供資訊。將 DPC 新增至 DPC 佇列時，驅動程式會將此值當做 SystemArgument1 參數提供給 KeInsertQueueDpc。

針對 CustomTimerDpc，不會使用此值。

[in, optional] SystemArgument2

指定驅動程式定義的內容資訊。將 DPC 新增至 DPC 佇列時，驅動程式會將此值當做 SystemArgument2 參數提供給 KeInsertQueueDpc。

針對 CustomTimerDpc，不會使用此值。

傳回值

無

備註

若要建立 DPC 物件並註冊該物件的 CustomDpc 例程，驅動程式必須呼叫 KeInitializeDpc。 (如果您需要一個 DPC 例程，您可以使用 DpcForIsr 例程和系統配置的 DPC 物件。)

若要將 CustomDpc 例程排入佇列以執行，驅動程式的 InterruptService 例程必須呼叫 KeInsertQueueDpc。

您可以使用一或多個 CustomDpc 例程，而不是 或與 DpcForIsr 例程搭配使用。維護數個內部 IRP 佇列的驅動程式通常會為每個佇列提供 CustomDpc 例程。每個 CustomDpc 例程通常至少負責下列工作：

完成目前 IRP 所描述的 I/O 作業。
從其中一個驅動程式的 IRP 佇列取消佇列下一個 IRP。 (使用系統提供的 IRP 佇列與 StartIo 例程呼叫 IoStartNextPacket.)
在目前的 IRP 中設定 I/O 狀態區塊，並針對已完成的要求呼叫 IoCompleteRequest 。

CustomDpc 例程可能也會重試失敗的作業，或針對已分成較小片段的大型 I/O 要求設定下一次傳輸。

如需 CustomDpc 例程的詳細資訊，請參閱 DPC 物件和 DPC。

驅動程式會呼叫 KeInitializeThreadedDpc，為 DPC 對象註冊 CustomThreadedDpc。若要實際將 DPC 新增至 DPC 佇列，以便執行 CustomThreadedDpc 例程，請呼叫 KeInsertQueueDpc。

如需使用 CustomThreadedDpc 例程的詳細資訊，請參閱線程式 DPC 簡介。

CustomThreadedDpc 例程可以在 IRQL = DISPATCH_LEVEL上執行，也可以在即時線程中於 IRQL = PASSIVE_LEVEL執行。

若要建立 DPC 物件並註冊該物件的 CustomTimerDpc 例程，驅動程式必須呼叫 KeInitializeDpc。

若要將 CustomTimerDpc 例程排入佇列以執行，驅動程式例程必須呼叫 KeSetTimer 或 KeSetTimerEx，並提供 KeInitializeDpc 傳回的 DPC 物件指標。當定時器間隔到期時，系統會呼叫 CustomTimerDpc 例程。

如需 CustomTimerDpc 例程的詳細資訊，請參閱定時器物件和 DPC。

範例

若要定義回呼例程，您必須先提供函式宣告，以識別您要定義的回呼例程類型。 Windows 提供一組驅動程式的回呼函式類型。使用回呼函式類型宣告函式有助於驅動程式的程式代碼分析、靜態驅動程式驗證器 (SDV) ，以及其他驗證工具會尋找錯誤，而且這是撰寫 Windows 操作系統驅動程式的需求。

例如，若要定義名為 MyCustomDpc的 CustomDpc 回呼例程，請使用 KDEFERRED_ROUTINE 類型，如下列程式代碼範例所示：

KDEFERRED_ROUTINE MyCustomDpc;

然後，實作回呼例程，如下所示：

_Use_decl_annotations_
VOID
  MyCustomDpc(
    struct _KDPC  *Dpc,
    PVOID  DeferredContext,
    PVOID  SystemArgument1,
    PVOID  SystemArgument2
    )
  {
      // Function body
  }