WdfUsbTargetDeviceCreateUrb-Funktion (wdfusb.h)

Artikel
08/08/2023

[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 von einem vorherigen Aufruf von WdfUsbTargetDeviceCreateWithParameters abgerufen 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-Element der Struktur ein USB-Geräteobjekt (WDFUSBDEVICE) oder ein vom Framework erstelltes Anforderungsobjekt (WDFREQUEST) oder ein beliebiges Objekt sein, dessen Kette von übergeordneten Elementen zu einem dieser Typen führt. Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[out] UrbMemory

Ein Zeiger auf einen WDFMEMORY-typisierten Speicherort, der ein Handle für ein Frameworkspeicherobjekt empfängt.

[out, optional] Urb

Ein Zeiger auf eine URB-Struktur, die die Adresse der neu zugewiesenen 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, als er WDF_USB_DEVICE_CREATE_CONFIG_INIT aufgerufen hat.
STATUS_INSUFFICIENT_RESOURCES	Es war nicht genügend Arbeitsspeicher vorhanden, um eine neue URB zu erstellen.

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

Hinweise

Vor dem Aufrufen von WdfUsbTargetDeviceCreateUrb muss ein Treiber WdfUsbTargetDeviceCreateWithParameters aufrufen. Bei erfolgreicher Ausführung gibt WdfUsbTargetDeviceCreateUrb ein Handle an ein Frameworkspeicherobjekt zurück, das die neu zugewiesene URB beschreibt. In der Regel ruft ein Treiber WdfUsbTargetDeviceCreateUrb innerhalb eines Anforderungshandlers auf.

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

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

Wenn der Treiber beim Aufrufen von WdfUsbTargetDeviceCreateUrb einen Urb-Parameter bereitstellt, können Sie die URB manuell oder durch Aufrufen der UsbBuildXxx-Routinen formatieren.

Das Speicherobjekt und sein Puffer werden gelöscht, wenn das übergeordnete Objekt gelöscht wird. Ein Treiber kann auch ein Speicherobjekt und seinen Puffer löschen, indem er WdfObjectDelete aufruft.

Beispiele

Im folgenden Codebeispiel wird ein Frameworkspeicherobjekt deklariert. Das Beispiel ruft WdfUsbTargetDeviceCreateUrb auf, 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
Unterstützte Mindestversion (Client)	Windows Vista
Zielplattform	Universell
KMDF-Mindestversion	1.11
Kopfzeile	wdfusb.h (einschließlich Wdfusb.h)
Bibliothek	Wdf01000.sys (siehe Versionierung der Frameworkbibliothek.)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf)

Weitere Informationen

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreateIsochUrb

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceFormatRequestForUrb

Freigeben über