共用方式為


WdfIoTargetPurge 函式 (wdfiotarget.h)

[適用於 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

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

[in] Action

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

傳回值

備註

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

如果驅動程式先前已呼叫 WdfUsbTargetPipeConfigContinuousReader,則必須在 IRQL = PASSIVE_LEVEL呼叫 WdfIoTargetPurge 。 如果驅動程式尚未呼叫 WdfUsbTargetPipeConfigContinuousReader,而且如果 WdfIoTargetPurgeAction 參數是 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 來重新啟動佇列。

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

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

  1. 呼叫 WdfIoTargetPurge 並指定 WdfIoTargetPurgeIoAction 值。
  2. 判斷目標是否應該繼續處理 I/O 要求。
  3. 如果目標應該繼續,請呼叫 WdfIoTargetStart。 否則,請使用 WdfIoTargetPurgeIoAndWaitAction 值再次呼叫 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)

另請參閱

WDF_IO_TARGET_PURGE_IO_ACTION

WdfIoTargetCreate

WdfIoTargetGetState

WdfIoTargetStart

WdfIoTargetStop