共用方式為

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），或是父系鏈結導致其中一種類型的任何物件。 這個參數是選擇性的，而且可以WDF_NO_OBJECT_ATTRIBUTES。

[out] UrbMemory

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

[out, optional] Urb

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

傳回值

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

傳回碼 描述
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
目標平臺 普遍
最低 KMDF 版本 1.11
標頭 wdfusb.h （包括 Wdfusb.h）
連結庫 Wdf01000.sys （請參閱架構連結庫版本控制。）
IRQL <=DISPATCH_LEVEL
DDI 合規性規則 DriverCreate（kmdf）

另請參閱

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreateIsochUrb

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceFormatRequestForUrb