WdfUsbTargetDeviceCreateUrb 函式 (wdfusb.h)

  • 發行項

[僅適用於 KMDF]

WdfUsbTargetDeviceCreateUrb 方法會配置 USB 要求區塊 (URB) 。

語法

NTSTATUS WdfUsbTargetDeviceCreateUrb(
  [in]            WDFUSBDEVICE           UsbDevice,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]           WDFMEMORY              *UrbMemory,
  [out, optional] PURB                   *Urb
);

參數

[in] UsbDevice

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

[in, optional] Attributes

呼叫端所提供 之WDF_OBJECT_ATTRIBUTES 結構的指標，其中包含新記憶體對象的屬性。 如果驅動程式提供此參數，結構的 ParentObject 成員必須是 USB 裝置物件， (WDFUSBDEVICE) 或由架構建立的 WDFREQUEST) (WDFREQUEST) ，或是父系鏈結會導致這些類型的任何物件。 這個參數是選擇性的，而且可以WDF_NO_OBJECT_ATTRIBUTES。

[out] UrbMemory

接收架構記憶體物件句柄之 WDFMEMORY 型別位置的指標。

[out, optional] Urb

URB 結構的指標，可接收新配置的 URB 位址。 這個參數是選擇性的，而且可以是 NULL。

傳回值

如果作業成功，WdfUsbTargetDeviceCreateUrb 會傳回STATUS_SUCCESS。 否則，這個方法可以傳回下列其中一個值：

傳回碼 Description
STATUS_INVALID_PARAMETER
 偵測到無效的參數。
STATUS_INVALID_DEVICE_STATE
 驅動程式在呼叫 WDF_USB_DEVICE_CREATE_CONFIG_INIT 時未指定用戶端合約版本。
STATUS_INSUFFICIENT_RESOURCES
 記憶體不足，無法建立新的 URB。
 

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

備註

在呼叫 WdfUsbTargetDeviceCreateUrb 之前，驅動程式必須呼叫 WdfUsbTargetDeviceCreateWithParameters。 如果成功， WdfUsbTargetDeviceCreateUrb 會傳回描述新配置 URB 之架構記憶體物件的句柄。 一般而言，驅動程式會從要求處理程式內呼叫 WdfUsbTargetDeviceCreateUrb。

驅動程式可以呼叫 WdfUsbTargetDeviceCreateUrb 來配置 URB 結構，再呼叫 WdfUsbTargetDeviceFormatRequestForUrb。

WdfUsbTargetDeviceCreateUrb 的運作方式與 WdfMemoryCreate 類似。 這兩種方法都會配置架構記憶體物件，而且這兩種方法也都提供接收緩衝區 (的選項，在此情況下，URB) 與記憶體對象相關聯。 在這兩種情況下，呼叫端稍後也可以藉由呼叫 WdfMemoryGetBuffer 來擷取緩衝區。

如果驅動程式在呼叫 WdfUsbTargetDeviceCreateUrb 時提供 Urb 參數，您可以手動或呼叫 UsbBuildXxx 例程來格式化 URB。

刪除父物件時，會刪除記憶體物件及其緩衝區。 驅動程式也可以藉由呼叫 WdfObjectDelete 來刪除記憶體物件及其緩衝區。

範例

下列程式代碼範例會宣告架構記憶體物件。 此範例會呼叫 WdfUsbTargetDeviceCreateUrb 來配置 USB 要求區塊，然後呼叫 WdfUsbTargetDeviceFormatRequestForUrb 來格式化使用 URB 結構內容的要求。 最後，此範例會註冊 CompletionRoutine 回呼函式，並將要求傳送至 I/O 目標。

WDFMEMORY memory;
PURB urb = NULL;

WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);
objectAttribs.ParentObject = UsbDevice;

status = WdfUsbTargetDeviceCreateUrb(
    pDevContext->WdfUsbTargetDevice,
    &objectAttribs,
    &memory,
    &urb);

status = WdfUsbTargetDeviceFormatRequestForUrb(
    deviceContext->WdfUsbTargetDevice,
    request,
    memory,
    NULL);

WdfRequestSetCompletionRoutine(
    request,
    MyCompletionRoutine,
    NULL);

if (!WdfRequestSend(
        request,
        WdfUsbTargetDeviceGetIoTarget(UsbDevice),
        NULL)) {
    status = WdfRequestGetStatus(request);
}

規格需求

需求 值
最低支援的用戶端 Windows Vista
目標平台 Universal
最低 KMDF 版本 1.11
標頭 wdfusb.h (包含 Wdfusb.h)
程式庫 Wdf01000.sys (請參閱 Framework Library Versioning.)
IRQL <=DISPATCH_LEVEL
DDI 合規性規則 DriverCreate (kmdf)

另請參閱

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreateIsochUrb

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceFormatRequestForUrb