WdfUsbTargetDeviceSendUrbSynchronously 函式 (wdfusb.h)

發行項
02/27/2024

[僅適用於 KMDF]

WdfUsbTargetDeviceSendUrbSynchronously 方法會使用 URB 所描述的要求參數，以同步方式將 USB 要求傳送至指定的 USB 裝置。

語法

NTSTATUS WdfUsbTargetDeviceSendUrbSynchronously(
  [in]           WDFUSBDEVICE              UsbDevice,
  [in, optional] WDFREQUEST                Request,
  [in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [in]           PURB                      Urb
);

參數

[in] UsbDevice

從先前呼叫 WdfUsbTargetDeviceCreateWithParameters 取得的 USB 裝置物件的句柄。

[in, optional] Request

架構要求物件的句柄。此參數是選擇性的，可以是 NULL。如需詳細資訊，請參閱接下來的＜備註＞一節。

[in, optional] RequestOptions

呼叫端配置的 WDF_REQUEST_SEND_OPTIONS 結構的指標，指定要求的選項。此指標是選擇性的，可以是 NULL。如需詳細資訊，請參閱接下來的＜備註＞一節。

[in] Urb

呼叫端初始化 URB 結構的指標。

如果驅動程式先前稱為 WdfUsbTargetDeviceCreateWithParameters 來建立 UsbDevice，驅動程式必須使用 WdfUsbTargetDeviceCreateUrb 或 WdfUsbTargetDeviceCreateIsochUrb 來建立此 URB。

傳回值

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

傳回碼	Description
STATUS_INVALID_PARAMETER	偵測到無效的參數。
STATUS_INVALID_DEVICE_REQUEST	呼叫端的 IRQL 無效。
STATUS_INSUFFICIENT_RESOURCES	記憶體不足。
STATUS_IO_TIMEOUT	驅動程式提供了逾時值，而且要求未在分配的時間內完成。

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

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

備註

使用 WdfUsbTargetDeviceSendUrbSynchronously 方法來同步傳送 USB 控制項傳輸要求。若要以異步方式傳送這類要求，請使用 WdfUsbTargetDeviceFormatRequestForUrb，後面接著 WdfRequestSend。

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

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

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

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

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

不論驅動程式是否提供非 NULL 或NULL要求參數，您的驅動程式都可以指定非 NULLRequestOptions 參數。例如，您可以使用 RequestOptions 參數來指定逾時值。

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

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

範例

下列程式代碼範例會初始化 URB 結構，並呼叫 WdfUsbTargetDeviceSendUrbSynchronously。

URB Urb;
NTSTATUS status;

Urb.UrbHeader.Function =  URB_FUNCTION_GET_CONFIGURATION;
Urb.UrbHeader.Length = sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST);
Urb.UrbControlGetConfigurationRequest.TransferBufferLength = 1 ; // Must be 1
Urb.UrbControlGetConfigurationRequest.TransferBufferMDL = NULL;
Urb.UrbControlGetConfigurationRequest.TransferBuffer = outBuffer;
Urb.UrbControlGetConfigurationRequest.UrbLink = NULL;

status = WdfUsbTargetDeviceSendUrbSynchronously(
                                                UsbDevice,
                                                NULL,
                                                NULL,
                                                &Urb
                                                );

規格需求

需求	值
目標平台	Universal
最小 KMDF 版本	1.0
標頭	wdfusb.h (包含 Wdfusb.h)
程式庫	Wdf01000.sys (請參閱 Framework Library Versioning.)
IRQL	PASSIVE_LEVEL
DDI 合規性規則	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf) 、 SyncReqSend (kmdf) 、 UsbKmdfIrql (kmdf) 、 UsbKmdfIrql2 (kmdf) 、UsbKmdfIrqlExplicit (kmdf)