WdfUsbTargetPipeAbortSynchronously 函式 (wdfusb.h)

  • 發行項

[適用於 KMDF 和 UMDF]

WdfUsbTargetPipeAbortSynchronously 方法會建置中止要求，並以同步方式將它傳送至指定的 USB 管道。

語法

NTSTATUS WdfUsbTargetPipeAbortSynchronously(
  [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。 如需詳細資訊，請參閱接下來的＜備註＞一節。

傳回值

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

傳回碼 Description
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
 驅動程式提供逾時值，且要求未在配置的時間內完成。
 

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

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

備註

使用 WdfUsbTargetPipeAbortSynchronously 方法來同步傳送 USB 中止要求。 若要以異步方式傳送這類要求，請使用 WdfUsbTargetPipeFormatRequestForAbort，後面接著 WdfRequestSend。

USB 中止要求會導致驅動程式的 I/O 目標取消傳送至管道的所有 I/O 要求。 當驅動程式 呼叫 WdfUsbTargetPipeAbortSynchronously 時，架構會將 URB_FUNCTION_ABORT_PIPE 要求傳送至 I/O 目標。 如需在 USB 管道上取消作業的詳細資訊， (也稱為「中止管道」) ，請參閱 USB 規格。

除非驅動程式在 RequestOptions 參數的 WDF_REQUEST_SEND_OPTIONS 結構中提供逾時值，否則 WdfUsbTargetPipeAbortSynchronously 方法不會傳回，除非偵測到錯誤。

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

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

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

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

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

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

範例

下列程式代碼範例會將中止要求傳送至針對USB裝置介面設定的所有管道。

UCHAR  i;
ULONG  count;
NTSTATUS  status;
PDEVICE_CONTEXT  pDevContext;

pDevContext = GetDeviceContext(Device);

count = WdfUsbInterfaceGetNumConfiguredPipes(
                                             pDevContext->UsbInterface
                                             );

for (i = 0; i < count; i++) {
    WDFUSBPIPE pipe;

    pipe = WdfUsbInterfaceGetConfiguredPipe(
                                            pDevContext->UsbInterface,
                                            i,
                                            NULL
                                            );
    status = WdfUsbTargetPipeAbortSynchronously(
                                                pipe,
                                                WDF_NO_HANDLE,
                                                NULL
                                                );
    if (!NT_SUCCESS(status)) {
        break;
    }
}

規格需求

需求 值
目標平台 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)

另請參閱

WdfRequestCancelSentRequest

WdfUsbTargetPipeResetSynchronously