Funzione WdfUsbTargetDeviceCreateUrb (wdfusb.h)

Articolo
08/08/2023

[Si applica solo a KMDF]

Il metodo WdfUsbTargetDeviceCreateUrb alloca un blocco di richieste USB (BLOCK).

Sintassi

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

Parametri

[in] UsbDevice

Handle per un oggetto dispositivo USB ottenuto da una chiamata precedente a WdfUsbTargetDeviceCreateWithParameters.

[in, optional] Attributes

Puntatore a una struttura di WDF_OBJECT_ATTRIBUTES fornita dal chiamante che contiene attributi per il nuovo oggetto memoria. Se il driver fornisce questo parametro, il membro ParentObject della struttura deve essere un oggetto dispositivo USB (WDFUSBDEVICE) o un oggetto request (WDFREQUEST) creato dal framework o qualsiasi oggetto la cui catena di elementi padre porta a uno di questi tipi. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.

[out] UrbMemory

Puntatore a una posizione tipizzata WDFMEMORY che riceve un handle per un oggetto memoria del framework.

[out, optional] Urb

Puntatore a unastrutturaae che che riceve l'indirizzo dell'OGGETTO APPENA allocato. Questo parametro è facoltativo e può essere NULL.

Valore restituito

WdfUsbTargetDeviceCreateUrb restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo può restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido.
STATUS_INVALID_DEVICE_STATE	Il driver non ha specificato una versione del contratto client quando ha chiamato WDF_USB_DEVICE_CREATE_CONFIG_INIT.
STATUS_INSUFFICIENT_RESOURCES	Memoria insufficiente per creare un nuovo ELEMENTO).

Questo metodo potrebbe anche restituire altri valori NTSTATUS.

Commenti

Prima di chiamare WdfUsbTargetDeviceCreateUrb, un driver deve chiamare WdfUsbTargetDeviceCreateWithParameters. In caso di esito positivo, WdfUsbTargetDeviceCreateUrb restituisce un handle a un oggetto memoria del framework che descrive l'oggetto THREAD appena allocato. In genere, un driver chiama WdfUsbTargetDeviceCreateUrb dall'interno di un gestore di richieste.

Un driver può chiamare WdfUsbTargetDeviceCreateUrb per allocare una struttura ODBC prima di chiamare WdfUsbTargetDeviceFormatRequestForUrb.

WdfUsbTargetDeviceCreateUrb è simile nell'operazione a WdfMemoryCreate. Entrambi i metodi allocano un oggetto memoria del framework e entrambi i metodi forniscono anche la possibilità di ricevere il buffer (in questo caso, l'oggetto ROUTE) associato all'oggetto memory. In entrambi i casi, il chiamante può anche recuperare il buffer in un secondo momento chiamando WdfMemoryGetBuffer.

Se il driver fornisce unparametroo quando chiama WdfUsbTargetDeviceCreateUrb, è possibile formattare manualmente o chiamando le routine UsbBuildXxx.

L'oggetto memory e il relativo buffer vengono eliminati quando l'oggetto padre viene eliminato. Un driver può anche eliminare un oggetto memoria e il relativo buffer chiamando WdfObjectDelete.

Esempio

Nell'esempio di codice seguente viene dichiarato un oggetto memoria del framework. Nell'esempio viene chiamato WdfUsbTargetDeviceCreateUrb per allocare un blocco di richieste USB e quindi viene chiamato WdfUsbTargetDeviceFormatRequestForUrb per formattare una richiesta che usa il contenuto dellastrutturaae. Infine, l'esempio registra una funzione di callback CompletionRoutine e invia la richiesta a una destinazione di I/O.

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

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista
Piattaforma di destinazione	Universale
Versione KMDF minima	1.11
Intestazione	wdfusb.h (include Wdfusb.h)
Libreria	Wdf01000.sys (vedere Controllo delle versioni della libreria framework).
IRQL	<=DISPATCH_LEVEL
Regole di conformità DDI	DriverCreate(kmdf)

Vedi anche

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreateIsochUrb

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceFormatRequestForUrb

Condividi tramite