USBD_UrbAllocate-Funktion (usbdlib.h)

Artikel
02/07/2025

Die USBD_UrbAllocate Routine weist einen USB-Anforderungsblock (URB) zu.

Syntax

NTSTATUS USBD_UrbAllocate(
  [in]  USBD_HANDLE USBDHandle,
  [out] PURB        *Urb
);

Parameter

[in] USBDHandle

USBD-Handle, das vom Clienttreiber in einem vorherigen Aufruf der USBD_CreateHandle Routine abgerufen wird.

[out] Urb

Zeiger auf die neu zugeordnete URB--Struktur. Alle Elemente der Struktur sind auf Null festgelegt. Der Clienttreiber muss die URB freigeben, wenn der Treiber die Verwendung beendet hat, indem er USBD_UrbFreeaufruft.

Rückgabewert

Die USBD_UrbAllocate Routine gibt STATUS_SUCCESS zurück, wenn die Anforderung erfolgreich ist. Andernfalls legt USBD_UrbAllocateUrb- auf NULL fest und gibt einen Fehlercode zurück.

Mögliche Werte sind, aber nicht beschränkt auf, STATUS_INVALID_PARAMETER, die angibt, dass der Aufrufer in NULL an USBDHandle oder Urbübergeben.

Bemerkungen

Die USBD_UrbAllocate Routine ermöglicht es dem zugrunde liegenden USB-Treiberstapel, einen undurchsichtigen URB-Kontext für die URB zuzuweisen. Mithilfe des URB-Kontexts kann der USB-Treiberstapel Anforderungen effizienter und zuverlässiger verarbeiten. Diese Optimierungen werden vom USB 3.0-Treiberstapel bereitgestellt, der in Windows 8 enthalten ist. Der Clienttreiber kann nicht auf den URB-Kontext zugreifen; der Kontext wird intern vom Bustreiber verwendet.

Unabhängig von der USB-Protokollversion des Hostcontrollers, dem zugrunde liegenden USB-Treiberstapel, dem Zielbetriebssystem, muss der Clienttreiber immer USBD_UrbAllocate aufrufen, um eine URB- Struktur zuzuweisen. USBD_UrbAllocate ersetzt frühere Zuordnungsmechanismen, z. B. ExAllocatePoolWithTag, oder die Zuordnung auf dem Stapel.

Der Clienttreiber muss nichtUSBD_UrbAllocateverwenden,

Um eine URB mit variabler Länge zuzuweisen, z. B. eine URB für eine isochrone Übertragung. Stattdessen muss der Clienttreiber USBD_IsochUrbAllocateaufrufen.
Wenn das Zielbetriebssystem Windows XP mit Service Pack 2 (SP2) oder einer früheren Version von Windows ist.

Weitere Informationen zu Ersetzungsroutinen finden Sie unter Allocating and Building URBs.

Sie müssen USBD_UrbFree aufrufen, um die von USBD_UrbAllocatezugewiesene URB freizugeben.

Beispiele

Im folgenden Codebeispiel wird gezeigt, wie Sie eine URB zuordnen, übermitteln und freigeben. Im Beispiel wird die URB synchron übermittelt. Die Implementierung der SubmitUrbSync-Funktion finden Sie im Beispielabschnitt in How to Submit an URB.

NTSTATUS CreateandSubmitURBSynchronously (
    _In_ USBD_HANDLE USBDHandle 
{
    PURB    Urb = NULL;

    NTSTATUS status;

    status = USBD_UrbAllocate(USBDHandle, &Urb);

    if (!NT_SUCCESS(status))
    {
        goto CreateandSubmitURBExit;
    }

    //Format the URB for the request. Not Shown.
    status = BuildURBForBulkTransfer (Urb);

    if (!NT_SUCCESS(status))
    {
        goto CreateandSubmitURBExit;
    }

    status = SubmitUrbSync( TargetDeviceObject,
        Urb)  

    if (!NT_SUCCESS(status))
    {
        goto CreateandSubmitURBExit;
    }

CreateandSubmitURBExit:

    if (Urb)
    {
        USBD_UrbFree( USBDHandle, Urb); 
    }

    return status;

}

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Erfordert WDK für Windows 8. Zielt auf Windows Vista und höhere Versionen des Windows-Betriebssystems ab.
Zielplattform-	Desktop
Header-	usbdlib.h
Library	Usbdex.lib
IRQL-	DISPATCH_LEVEL

Siehe auch

Zuweisung und Erstellen von URBs

Senden von Anforderungen an ein USB-Gerät

USBD_UrbFree

Freigeben über