WdfUsbTargetPipeResetSynchronously 函式 (wdfusb.h)
[適用於 KMDF 和 UMDF]
WdfUsbTargetPipeResetSynchronously 方法會建置重設要求,並以同步方式將它傳送至指定的 USB 管道。
語法
NTSTATUS WdfUsbTargetPipeResetSynchronously(
[in] WDFUSBPIPE Pipe,
[in, optional] WDFREQUEST Request,
[in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions
);
參數
[in] Pipe
呼叫 WdfUsbInterfaceGetConfiguredPipe 取得之架構管道物件的句柄。
[in, optional] Request
架構要求物件的句柄。 此參數是選擇性的,可以是 NULL。 如需詳細資訊,請參閱接下來的<備註>一節。
[in, optional] RequestOptions
呼叫端配置的 WDF_REQUEST_SEND_OPTIONS 結構的指標,指定要求的選項。 此指標是選擇性的,可以是 NULL。 如需詳細資訊,請參閱接下來的<備註>一節。
傳回值
WdfUsbTargetPipeResetSynchronously 會在作業成功時傳回 USB I/O 目標的完成狀態值。 否則,此方法可以傳回下列其中一個值:
傳回碼 | Description |
---|---|
|
指定 RequestOptions 參數的WDF_REQUEST_SEND_OPTIONS結構大小不正確。 |
|
偵測到無效的參數。 |
|
記憶體不足。 |
|
呼叫端的 IRQL 未PASSIVE_LEVEL,或指定的 Request 參數已排入 I/O 目標的 I/O 要求。 |
|
驅動程式提供了逾時值,而且要求未在分配的時間內完成。 |
|
要求參數所代表的 I/O 要求封包 (IRP) 沒有足夠的IO_STACK_LOCATION結構,可讓驅動程式轉送要求。 |
這個方法也可能傳回其他 NTSTATUS值。
如果驅動程式提供無效的物件句柄,就會發生錯誤檢查。
備註
使用 WdfUsbTargetPipeResetSynchronously 方法來同步傳送 USB 重設要求。 若要以異步方式傳送這類要求,請使用 WdfUsbTargetPipeFormatRequestForReset,後面接著 WdfRequestSend。
在架構重設 I/O 目標的 USB 管道之前,它會取消保留在 I/O 目標佇列中的所有 I/O 要求。 在 WdfUsbTargetPipeResetSynchronously 傳回之前,驅動程式不得將額外的 I/O 要求傳送至 I/O 目標。
驅動程式必須先呼叫 WdfIoTargetStop ,才能呼叫 WdfUsbTargetPipeResetSynchronously。 在 WdfUsbTargetPipeResetSynchronously 傳回之後,驅動程式可以呼叫 WdfIoTargetStart。
當驅動程式呼叫 WdfUsbTargetPipeResetSynchronous 時,架構會將 URB_FUNCTION_RESET_PIPE 要求傳送至 I/O 目標。 如需重設 USB 管道的詳細資訊,請參閱 USB 規格。
除非驅動程式在 RequestOptions 參數指向的 WDF_REQUEST_SEND_OPTIONS 結構中提供逾時值,否則 WdfUsbTargetPipeResetSynchronously 方法不會傳回,除非偵測到錯誤。
您可以轉送驅動程式在 I/O 佇列中收到的 I/O 要求,也可以建立並傳送新的要求。
若要轉送驅動程式在 I/O 佇列中收到的 I/O 要求,請為 WdfUsbTargetPipeResetSynchronously 方法的 Request 參數指定收到的要求句柄。
若要建立並傳送新的要求,請提供 Request 參數的 NULL 要求句柄,或建立新的要求物件並提供其句柄:
- 如果您提供 NULL 要求句柄,架構會使用內部要求物件。 這項技術很容易使用,但驅動程式無法取消要求。
- 如果您呼叫 WdfRequestCreate 來建立一或多個要求物件,您可以呼叫 WdfRequestReuse 來重複使用這些要求物件。 這項技術可讓驅動程式的 EvtDriverDeviceAdd 回呼函式預先配置裝置的要求物件。 此外,另一個驅動程式線程可以視需要呼叫 WdfRequestCancelSentRequest 來取消要求。
如需 I/O 要求完成之後取得狀態資訊的相關信息,請參閱 取得完成資訊。
如需 WdfUsbTargetPipeResetSynchronously 方法和 USB I/O 目標的詳細資訊,請參閱 USB I/O 目標。
範例
下列程式代碼範例會將重設要求傳送至USB裝置的管道。
NTSTATUS status;
status = WdfUsbTargetPipeResetSynchronously(
Pipe,
WDF_NO_HANDLE,
NULL
);
規格需求
需求 | 值 |
---|---|
目標平台 | Universal |
最小 KMDF 版本 | 1.0 |
最低UMDF版本 | 2.0 |
標頭 | wdfusb.h (包含 Wdfusb.h) |
程式庫 | Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF) |
IRQL | PASSIVE_LEVEL |
DDI 合規性規則 | DriverCreate (kmdf) , KmdfIrql (kmdf) , KmdfIrql2 (kmdf) , KmdfIrqlExplicit (kmdf) , RequestForUrbXrb (kmdf) 、 UsbKmdfIrql (kmdf) 、 UsbKmdfIrql2 (kmdf) 、UsbKmdfIrqlExplicit (kmdf) |
另請參閱
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應