USBD_UrbAllocate-Funktion (usbdlib.h)

Artikel
02/26/2024

Die USBD_UrbAllocate Routine weist einen USB Request Block (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 0 festgelegt. Der Clienttreiber muss die URB freigeben, wenn der Treiber die Verwendung abgeschlossen hat, indem er USBD_UrbFree aufruft.

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 unter anderem STATUS_INVALID_PARAMETER, die angibt, dass der Aufrufer in NULL an USBDHandle oder Urb übergeben wird.

Hinweise

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 durch den 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 und dem Zielbetriebssystem muss der Clienttreiber immer USBD_UrbAllocate aufrufen, um eine URB-Struktur zuzuweisen. USBD_UrbAllocate ersetzt frühere Zuordnungsmechanismen wie ExAllocatePoolWithTag oder deren Zuordnung im Stapel.

Der Clienttreiber darf nichtUSBD_UrbAllocate verwenden.

So weisen Sie eine URB mit variabler Länge zu, z. B. eine URB für eine isochrone Übertragung. Stattdessen muss der Clienttreiber USBD_IsochUrbAllocate aufrufen.
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 Zuweisen und Erstellen von URBs.

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

Beispiele

Im folgenden Codebeispiel wird gezeigt, wie sie eine URB zuordnen, übermitteln und freigeben. Im Beispiel wird die URB synchron übermittelt. Informationen zur Implementierung der SubmitUrbSync-Funktion finden Sie im Beispielabschnitt unter Übermitteln einer 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
Unterstützte Mindestversion (Client)	Erfordert WDK für Windows 8. Zielt auf Windows Vista und höhere Versionen des Windows-Betriebssystems ab.
Zielplattform	Desktop
Kopfzeile	usbdlib.h
Bibliothek	Usbdex.lib
IRQL	DISPATCH_LEVEL

Weitere Informationen

Zuweisung und Erstellen von URBs

Senden von Anforderungen an ein USB-Gerät

USBD_UrbFree

Freigeben über