WdfUsbTargetPipeFormatRequestForReset 函式 (wdfusb.h)

  • 發行項

[適用於 KMDF 和 UMDF]

WdfUsbTargetPipeFormatRequestForReset 方法會建置指定 USB 管道的重設要求，但不會傳送要求。

語法

NTSTATUS WdfUsbTargetPipeFormatRequestForReset(
  [in] WDFUSBPIPE Pipe,
  [in] WDFREQUEST Request
);

參數

[in] Pipe

呼叫 WdfUsbInterfaceGetConfiguredPipe 取得之架構管道物件的句柄。

[in] Request

架構要求物件的句柄。 如需詳細資訊，請參閱接下來的＜備註＞一節。

傳回值

WdfUsbTargetPipeFormatRequestForReset 會在作業成功時傳回 USB I/O 目標的完成狀態值。 否則，此方法可以傳回下列其中一個值：

傳回碼 Description
STATUS_INVALID_PARAMETER
 偵測到無效的參數。
STATUS_INSUFFICIENT_RESOURCES
 記憶體不足。
STATUS_REQUEST_NOT_ACCEPTED
 要求參數所代表的 I/O 要求封包 (IRP) 沒有足夠的IO_STACK_LOCATION結構，可讓驅動程式轉送要求。
 

這個方法也可能傳回其他 NTSTATUS值。

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

備註

使用 WdfUsbTargetPipeFormatRequestForReset，後面接著 WdfRequestSend，以同步或異步方式傳送 USB 重設要求。 或者，使用 WdfUsbTargetPipeResetSynchronously 方法來同步傳送要求。

在驅動程式呼叫 WdfRequestSend 之前，它必須呼叫 WdfIoTargetStop ，而且必須 完成 或 取消 它已傳送至 I/O 目標的所有 I/O 要求。 在重設要求完成之前，驅動程式不得將額外的 I/O 要求傳送至 I/O 目標。

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

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

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

若要建立新的 I/O 要求，請呼叫 WdfRequestCreate 預先配置要求物件。 提供 WdfUsbTargetPipeFormatRequestForReset 方法 的 Request 參數的要求 句柄。 您可以呼叫 WdfRequestReuse 來重複使用要求物件。 驅動程式的 EvtDriverDeviceAdd 回呼函式可以預先配置裝置的要求物件。

呼叫 WdfUsbTargetPipeFormatRequestForReset 以格式化 I/O 要求之後，驅動程式必須呼叫 WdfRequestSend ，以同步或異步方式將要求傳送至 I/O 目標) (。

對使用相同要求 之 WdfUsbTargetPipeFormatRequestForReset 的多個呼叫不會造成額外的資源配置。 因此，為了減少 WdfRequestCreate 將傳回STATUS_INSUFFICIENT_RESOURCES的機會，驅動程式的 EvtDriverDeviceAdd 回呼函式可以呼叫 WdfRequestCreate 來預先配置裝置的一或多個要求物件。 驅動程式後續可以重複使用 (呼叫 WdfRequestReuse) 、重新格式化 (呼叫 WdfUsbTargetPipeFormatRequestForReset) ，然後重新傳送 (呼叫 WdfRequestSend) 每個要求物件，而不會有STATUS_INSUFFICIENT_RESOURCES從稍後呼叫 WdfRequestCreate 傳回值的風險。 如果參數值未變更，則針對重複使用的要求物件，對 WdfUsbTargetPipeFormatRequestForReset 的所有後續呼叫都會傳回STATUS_SUCCESS。 (如果驅動程式每次未呼叫相同的要求格式方法，可能會配置其他資源。)

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

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

範例

下列程式代碼範例會格式化USB管道的重設要求、註冊 CompletionRoutine 回呼函式，並傳送要求。

status = WdfUsbTargetPipeFormatRequestForReset(
                                               pipe,
                                               Request
                                               );
if (!NT_SUCCESS(status)) {
    goto Exit;
}

WdfRequestSetCompletionRoutine(
                               Request,
                               AbortCompletionRoutine,
                               pipe
                               );

if (WdfRequestSend(
                   Request,
                   WdfUsbTargetPipeGetIoTarget(pipe),
                   WDF_NO_SEND_OPTIONS
                   ) == FALSE) {
    status = WdfRequestGetStatus(Request);
    goto Exit;
}
Exit:
if (!NT_SUCCESS(status)) {
    WdfRequestCompleteWithInformation(
                                      Request,
                                      status,
                                      0
                                      );
}
return;

規格需求

需求 值
目標平台 Universal
最小 KMDF 版本 1.0
最低UMDF版本 2.0
標頭 wdfusb.h (包含 Wdfusb.h)
程式庫 Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL <=DISPATCH_LEVEL
DDI 合規性規則 DriverCreate (kmdf) ， KmdfIrql (kmdf) ， KmdfIrql2 (kmdf) ， KmdfIrqlExplicit (kmdf) ， RequestFormattedValid (kmdf) 、 RequestForUrbXrb (kmdf) 、 RequestSendAndForgetNoFormatting (kmdf) 、 RequestSendAndForgetNoFormatting2 (kmdf) 、 UsbKmdfIrql (kmdf) 、 UsbKmdfIrql2 (kmdf) 、UsbKmdfIrqlExplicit (kmdf)

另請參閱

WdfRequestSend

WdfUsbInterfaceGetConfiguredPipe