wdfIoTargetStop 函式 (wdfiotarget.h)

發行項
03/01/2024

[適用於 KMDF 和 UMDF]

WdfIoTargetStop 方法會停止將佇列要求傳送至本機或遠端 I/O 目標。

語法

void WdfIoTargetStop(
  [in] WDFIOTARGET                  IoTarget,
  [in] WDF_IO_TARGET_SENT_IO_ACTION Action
);

參數

[in] IoTarget

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

[in] Action

WDF_IO_TARGET_SENT_IO_ACTION型別值，指定如果目標尚未完成要求，架構應該如何處理驅動程式傳送至 I/O 目標的 I/O 要求。

傳回值

無

備註

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

如果您的驅動程式可以偵測可復原的裝置錯誤，您可能希望驅動程式呼叫 WdfIoTargetStop 以暫時停止傳送要求，稍後再呼叫 WdfIoTargetStart 以繼續傳送要求。

停止時，I/O 目標會繼續接受新的要求，但不會將已排入佇列的要求傳遞給適當的驅動程式。

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

如果驅動程式呼叫 WdfUsbTargetPipeConfigContinuousReader 來設定 USB 管道的連續讀取器，驅動程式的 EvtDeviceD0Exit 回呼函式必須呼叫 WdfIoTargetStop 以停止讀取器。

如果驅動程式已呼叫 WdfIoTargetStop，它仍然可以在要求的WDF_REQUEST_SEND_OPTIONS結構中設定WDF_REQUEST_OPTION_IGNORE_TARGET_STATE旗標，將要求傳送至目標。如果驅動程式設定此旗標，驅動程式可以傳送要求，例如在驅動程式呼叫 WdfIoTargetStop 之後，將 USB 管道重設 (WdfUsbTargetPipeResetSynchronously) 。

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

您的驅動程序必須以同步方式呼叫 WdfIoTargetStart 和 WdfIoTargetStop 。在驅動程式呼叫其中一個函式之後，它不得在第一次呼叫傳回之前呼叫任一函式。

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

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

注意WdfIoTargetStop 不是安全線程。從不同的線程同時呼叫 WdfIoTargetStop 並不安全。

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

如果驅動程式已針對管道呼叫 WdfUsbTargetPipeConfigContinuousReader ，則必須在 IRQL = PASSIVE_LEVEL呼叫 WdfIoTargetStop 。

如果驅動程式尚未呼叫 WdfUsbTargetPipeConfigContinuousReader，而且 WdfIoTargetStop 的 Action 參數是 WdfIoTargetLeaveSentIoPending，可以在 IRQL <= DISPATCH_LEVEL呼叫 WdfIoTargetStop。否則，會在 IRQL = PASSIVE_LEVEL呼叫 WdfIoTargetStop 。

範例

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

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

    WdfIoTargetStop(
                    WdfUsbTargetPipeGetIoTarget(pDeviceContext->InterruptPipe),
                    WdfIoTargetCancelSentIo
                    );

    return STATUS_SUCCESS;
}

規格需求

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