WdfIoTargetPurge 函式 (wdfiotarget.h)

發行項
02/29/2024

[適用於 KMDF 和 UMDF]

WdfIoTargetPurge 方法會取消排入本機、遠端或特製化 I/O 目標的所有 I/O 要求，並防止任何新的 I/O 要求排入佇列。方法也會嘗試取消已離開 I/O 目標的佇列並輸入較低驅動程式的 I/O 要求。

語法

void WdfIoTargetPurge(
  [in] WDFIOTARGET                   IoTarget,
  [in] WDF_IO_TARGET_PURGE_IO_ACTION Action
);

參數

[in] IoTarget

從先前呼叫 WdfDeviceGetIoTarget 或 WdfIoTargetCreate 取得的本機或遠端 I/O 目標物件的句柄，或從特製化 I/O 目標所提供的方法取得，例如 WdfUsbTargetPipeGetIoTarget。

[in] Action

WDF_IO_TARGET_PURGE_IO_ACTION型別值，指出架構是否應該等候從 WdfIoTargetPurge 傳回，直到所有傳遞的要求都完成或取消為止。

傳回值

無

備註

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

如果驅動程式先前已呼叫 WdfUsbTargetPipeConfigContinuousReader，則必須在 IRQL = PASSIVE_LEVEL呼叫 WdfIoTargetPurge 。如果驅動程式尚未呼叫 WdfUsbTargetPipeConfigContinuousReader，而且如果 WdfIoTargetPurge 的 Action 參數是 WdfIoTargetPurgeIo，可以在 IRQL <= DISPATCH_LEVEL呼叫 WdfIoTargetPurge。否則，必須在 IRQL = PASSIVE_LEVEL呼叫 WdfIoTargetPurge 。

若要讓 WdfIoTargetPurge 成為同步呼叫，驅動程式可以設定 Action 參數的 WdfIoTargetPurgeIoAndWait 值。在此情況下， WdfIoTargetPurge 會等候傳回，直到所有傳遞的要求完成或取消為止。

在驅動程式呼叫 WdfIoTargetPurge 之後，它仍然可以藉由在要求的WDF_REQUEST_SEND_OPTIONS結構中設定WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE旗標，將要求傳送至目標。例如，驅動程式可能會傳送要求，例如在驅動程式呼叫 WdfIoTargetPurge 之後，將 USB 管道重設 (WdfUsbTargetPipeResetSynchronously) 到裝置。

當驅動程式呼叫 WdfIoTargetPurge 時，架構不會嘗試取消或等候先前使用要求WDF_REQUEST_SEND_OPTIONS結構中的WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE旗標或WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET旗標傳送至目標的 I/O 要求。

驅動程式清除 I/O 佇列之後，可以呼叫 WdfIoTargetStart 來重新啟動佇列。

您的驅動程序必須同步呼叫 WdfIoTargetStart、 WdfIoTargetStop 和 WdfIoTargetPurge 。在驅動程式呼叫其中一個函式之後，除非先前的呼叫傳回，否則它不得呼叫任何其他函式。

您的驅動程式可以多次呼叫 WdfIoTargetPurge ，而不需要呼叫 WdfIoTargetStart。例如，您的驅動程式可能會執行下列動作：

呼叫 WdfIoTargetPurge 並指定 WdfIoTargetPurgeIo 的 Action 值。
判斷目標是否應該繼續處理 I/O 要求。
如果目標應該繼續，請呼叫 WdfIoTargetStart。否則，請使用 WdfIoTargetPurgeIoAndWait 的 Action 值再次呼叫 WdfIoTargetPurge。

如需 I/O 目標狀態的詳細資訊，請參閱控制一般 I/O 目標的狀態。

如需 I/O 目標的詳細資訊，請參閱使用 I/O 目標。

範例

下列程式代碼範例示範如果驅動程式對 USB 管道使用連續讀取器， EvtDeviceD0Exit 回呼函式如何呼叫 WdfIoTargetPurge。

NTSTATUS
MyEvtDeviceD0Exit(
    IN  WDFDEVICE Device,
    IN  WDF_POWER_DEVICE_STATE TargetState
)
{
    PDEVICE_CONTEXT  pDeviceContext;
    pDeviceContext = GetMyDeviceContext(Device);

    WdfIoTargetPurge(
                    WdfUsbTargetPipeGetIoTarget(pDeviceContext->InterruptPipe),
                    WdfIoTargetPurgeIoAndWait
                    );

    return STATUS_SUCCESS;
}

規格需求

需求	值
目標平台	Universal
最小 KMDF 版本	1.11
最低UMDF版本	2.0
標頭	wdfiotarget.h (包含 Wdf.h)
程式庫	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	請參閱一節。
DDI 合規性規則	DriverCreate (kmdf)