WdfUsbTargetDeviceCreateUrb-Funktion (wdfusb.h)

Artikel
02/07/2025

[Gilt nur für KMDF]

Die WdfUsbTargetDeviceCreateUrb Methode weist einen USB-Anforderungsblock (URB) zu.

Syntax

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

Parameter

[in] UsbDevice

Ein Handle für ein USB-Geräteobjekt, das aus einem vorherigen Aufruf von WdfUsbTargetDeviceCreateWithParametersabgerufen wurde.

[in, optional] Attributes

Ein Zeiger auf eine vom Aufrufer bereitgestellte WDF_OBJECT_ATTRIBUTES Struktur, die Attribute für das neue Speicherobjekt enthält. Wenn der Treiber diesen Parameter bereitstellt, muss das ParentObject Member der Struktur ein USB-Geräteobjekt (WDFUSBDEVICE) oder ein vom Framework erstelltes Anforderungsobjekt (WDFREQUEST) oder ein Objekt sein, dessen Übergeordnete Kette zu einem dieser Typen führt. Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[out] UrbMemory

Ein Zeiger auf einen WDFMEMORY-typierten Speicherort, der ein Handle für ein Framework-Speicherobjekt empfängt.

[out, optional] Urb

Ein Zeiger auf eine URB-Struktur, die die Adresse der neu zugeordneten URB empfängt. Dieser Parameter ist optional und kann NULL sein.

Rückgabewert

WdfUsbTargetDeviceCreateUrb gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls kann diese Methode einen der folgenden Werte zurückgeben:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde erkannt.
STATUS_INVALID_DEVICE_STATE	Der Treiber hat keine Clientvertragsversion angegeben, wenn er WDF_USB_DEVICE_CREATE_CONFIG_INITaufgerufen hat.
STATUS_INSUFFICIENT_RESOURCES	Zum Erstellen eines neuen URB war nicht genügend Arbeitsspeicher vorhanden.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Bemerkungen

Vor dem Aufrufen WdfUsbTargetDeviceCreateUrbmuss ein Treiber WdfUsbTargetDeviceCreateWithParametersaufrufen. Bei erfolgreicher Ausführung gibt WdfUsbTargetDeviceCreateUrb ein Handle an ein Framework-Speicherobjekt zurück, das die neu zugeordnete URB beschreibt. In der Regel ruft ein Treiber WdfUsbTargetDeviceCreateUrb innerhalb eines Anforderungshandlersauf.

Ein Treiber kann WdfUsbTargetDeviceCreateUrb- aufrufen, um eine URB-Struktur zuzuweisen, bevor WdfUsbTargetDeviceFormatRequestForUrbaufgerufen wird.

WdfUsbTargetDeviceCreateUrb- ähnelt dem WdfMemoryCreate. Beide Methoden weisen ein Framework-Speicherobjekt zu, und beide Methoden bieten auch die Möglichkeit, den Puffer zu empfangen (in diesem Fall die URB), die dem Speicherobjekt zugeordnet ist. In beiden Fällen kann der Aufrufer den Puffer später auch abrufen, indem WdfMemoryGetBufferaufgerufen wird.

Wenn der Treiber einen Urb Parameter bereitstellt, wenn er WdfUsbTargetDeviceCreateUrbaufruft, können Sie die URB manuell formatieren oder indem Sie die UsbBuildXxx-Routinen aufrufen.

Das Speicherobjekt und dessen Puffer werden gelöscht, wenn das übergeordnete Objekt gelöscht wird. Ein Treiber kann auch ein Speicherobjekt und dessen Puffer löschen, indem WdfObjectDeleteaufgerufen wird.

Beispiele

Im folgenden Codebeispiel wird ein Frameworkspeicherobjekt deklariert. Im Beispiel wird WdfUsbTargetDeviceCreateUrb aufgerufen, um einen USB-Anforderungsblock zuzuweisen, und ruft dann WdfUsbTargetDeviceFormatRequestForUrb auf, um eine Anforderung zu formatieren, die den Inhalt der URB-Struktur verwendet. Schließlich registriert das Beispiel eine CompletionRoutine Rückruffunktion und sendet die Anforderung an ein E/A-Ziel.

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);
}

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista
Zielplattform-	Universal
Minimale KMDF-Version	1.11
Header-	wdfusb.h (include Wdfusb.h)
Library	Wdf01000.sys (siehe Framework-Bibliotheksversionsverwaltung.)
IRQL-	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf)

Siehe auch

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreateIsochUrb

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceFormatRequestForUrb

Freigeben über