共用方式為

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 目標的完成狀態值。 否則，這個方法可以傳回下列其中一個值：

傳回碼 描述
STATUS_INFO_LENGTH_MISMATCH
 RequestOptions 參數所指定之 WDF_REQUEST_SEND_OPTIONS 結構的大小不正確。
STATUS_INVALID_PARAMETER
 偵測到無效的參數。
STATUS_INSUFFICIENT_RESOURCES
 記憶體不足。
STATUS_INVALID_DEVICE_REQUEST
 呼叫端的 IRQL 未PASSIVE_LEVEL，或指定 要求 參數已排入 I/O 目標的 I/O 要求。
STATUS_IO_TIMEOUT
 驅動程式提供逾時值，且要求未在分配的時間內完成。
STATUS_REQUEST_NOT_ACCEPTED
 Request 參數所代表的 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。

當驅動程式呼叫 WdfUsbTargetPipeResetSynchronously時，架構會將 URB_FUNCTION_RESET_PIPE 要求傳送至 I/O 目標。 如需重設 USB 管道的詳細資訊，請參閱 USB 規格。

WdfUsbTargetPipeResetSynchronously 方法在要求完成之前不會傳回，除非驅動程式在 WDF_REQUEST_SEND_OPTIONS 結構中提供 RequestOptions 參數指向的逾時值，或除非偵測到錯誤。

您可以轉送驅動程式在 I/O 佇列中收到的 I/O 要求，也可以建立並傳送新的要求。

若要轉送驅動程式在 I/O 佇列中收到的 I/O 要求，請為 WdfUsbTargetPipeResetSynchronously 指定接收的要求句柄， 方法的 Request 參數。

若要建立和傳送新的要求，請提供 NULL 要求句柄給 Request 參數，或建立新的要求物件並提供其句柄：

  • 如果您提供 NULL 要求句柄，架構會使用內部要求物件。 這項技術很容易使用，但驅動程式無法取消要求。
  • 如果您呼叫 WdfRequestCreate 來建立一或多個要求物件，您可以呼叫 WdfRequestReuse來重複使用這些要求物件。 這項技術可讓您的驅動程式 EvtDriverDeviceAdd 回呼函式預先配置裝置的要求物件。 此外，另一個驅動程式線程可以視需要呼叫 WdfRequestCancelSentRequest 來取消要求。
您的驅動程式可以指定非NULLRequestOptions 參數、驅動程式提供非NULL 或 NULLRequest 參數。 例如，您可以使用 RequestOptions 參數來指定逾時值。

如需在 I/O 要求完成之後取得狀態資訊的相關信息，請參閱 取得完成資訊。

如需 WdfUsbTargetPipeResetSynchronously 方法和 USB I/O 目標的詳細資訊，請參閱 USB I/O 目標。

例子

下列程式代碼範例會將重設要求傳送至USB裝置的管道。

NTSTATUS  status;

status = WdfUsbTargetPipeResetSynchronously(
                                            Pipe, 
                                            WDF_NO_HANDLE,
                                            NULL
                                            );

要求

要求 價值
目標平臺 普遍
最低 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），要求ForUrbXrb（kmdf），UsbKmdfIrql（kmdf），UsbKmdfIrql2（kmdf），UsbKmdfIrqlExplicit（kmdf）

另請參閱

WdfObjectDereference

WdfRequestCancelSentRequest

WdfRequestSend

WdfUsbTargetPipeAbortSynchronously