funzione USBD_UrbAllocate (usbdlib.h)

La routine USBD_UrbAllocate alloca un blocco richiesta USB (URB).

Sintassi

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

Parametri

[in] USBDHandle

Handle USBD recuperato dal driver client in una chiamata precedente alla routine di USBD_CreateHandle .

[out] Urb

Puntatore alla nuova struttura DELL'AREA di distribuzione allocata. Tutti i membri della struttura sono impostati su zero. Il driver client deve liberare IL DRIVER al termine dell'uso del driver chiamando USBD_UrbFree.

Valore restituito

La routine USBD_UrbAllocate restituisce STATUS_SUCCESS se la richiesta ha esito positivo. In caso contrario, USBD_UrbAllocate imposta Il valore Null su NULL e restituisce un codice di errore.

I valori possibili includono, ma non sono limitati a, STATUS_INVALID_PARAMETER, che indica il chiamante passato in NULL a USBDHandle o Urb.

Commenti

La routine di USBD_UrbAllocate consente allo stack di driver USB sottostante di allocare un contesto opaco DELL'istanza di URB. Usando il contesto DI URB, lo stack di driver USB può elaborare le richieste in modo più efficiente e affidabile. Tali ottimizzazioni vengono fornite dallo stack di driver USB 3.0 incluso in Windows 8. Il driver client non può accedere al contesto DI GESTIONE dei dati; il contesto viene usato internamente dal conducente del bus.

Indipendentemente dalla versione del protocollo USB del controller host, lo stack di driver USB sottostante, il sistema operativo di destinazione, il driver client deve sempre chiamare USBD_UrbAllocate per allocare una struttura DI ASSEGNAZIONE . USBD_UrbAllocate sostituisce i meccanismi di allocazione precedenti, ad esempio ExAllocatePoolWithTag o assegnandoli nello stack.

Il driver client non deve usare USBD_UrbAllocate,

• Per allocare un VALORE DI ENTITÀ con lunghezza variabile, ad esempio UN VALORE DI PER UN trasferimento isochronous. Il driver client deve invece chiamare USBD_IsochUrbAllocate.
• Se il sistema operativo di destinazione è Windows XP con Service Pack 2 (SP2) o una versione precedente di Windows.

Per altre informazioni sulle routine di sostituzione, vedere Allocazione e compilazione degli URL.

È necessario chiamare USBD_UrbFree per rilasciare l'ASSEGNAZIONE DELL'assegnare da USBD_UrbAllocate.

Esempio

Nell'esempio di codice seguente viene illustrato come allocare, inviare e rilasciare UN'DESCRIZIONE. Nell'esempio viene inviato in modo sincrono l'oggetto URB. Per l'implementazione della funzione SubmitUrbSync, vedere la sezione di esempio 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;

}

Requisiti

Requisito	Valore
Client minimo supportato	Richiede WDK per Windows 8. Destinazione Windows Vista e versioni successive del sistema operativo Windows.
Piattaforma di destinazione	Desktop
Intestazione	usbdlib.h
Libreria	Usbdex.lib
IRQL	DISPATCH_LEVEL

Vedi anche

Allocazione e compilazione di URB

Invio di richieste a un dispositivo USB

USBD_UrbFree