Funzione WdfUsbTargetDeviceFormatRequestForUrb (wdfusb.h)
[Si applica solo a KMDF]
Il metodo WdfUsbTargetDeviceFormatRequestForUrb compila una richiesta USB per un dispositivo USB specificato, usando i parametri di richiesta descritti da un OGGETTO METHOD, ma non invia la richiesta.
Sintassi
NTSTATUS WdfUsbTargetDeviceFormatRequestForUrb(
[in] WDFUSBDEVICE UsbDevice,
[in] WDFREQUEST Request,
[in] WDFMEMORY UrbMemory,
[in, optional] PWDFMEMORY_OFFSET UrbMemoryOffset
);
Parametri
[in] UsbDevice
Handle per un oggetto dispositivo USB ottenuto da una chiamata precedente a WdfUsbTargetDeviceCreateWithParameters.
[in] Request
Handle per un oggetto richiesta del framework. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
[in] UrbMemory
Handle per un oggetto memoria del framework che contiene una struttura WM o uno dei membri dell'unione della struttura. Tutti i membri dell'unione della struttura DELL'ELENCO contengono la struttura _URB_HEADER .
Se il driver precedentemente chiamato WdfUsbTargetDeviceCreateWithParameters per creare UsbDevice, il driver deve usare WdfUsbTargetDeviceCreateUrb o WdfUsbTargetDeviceCreateIsochUrb per creare l'oggetto DEVICE contenuto in questo oggetto memoria. In caso contrario, si verifica un controllo di bug.
[in, optional] UrbMemoryOffset
Puntatore a una struttura WDFMEMORY_OFFSET allocata dal chiamante che fornisce valori facoltativi di offset di byte e lunghezza. Il framework usa questi valori per determinare l'indirizzo iniziale dell'oggetto ROUTE all'interno della memoria specificata da EsegueMemory . Se questo puntatore è NULL, l'OGGETTO VERRÀ posizionato all'inizio della memoria DioMemory .
Valore restituito
WdfUsbTargetDeviceFormatRequestForUrb restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo può restituire uno dei valori seguenti:
| Codice restituito | Descrizione |
|---|---|
|
È stato rilevato un parametro non valido. |
|
Memoria insufficiente. |
|
Offset non valido per il parametro UsbMemoryOffset specificato. |
Questo metodo potrebbe anche restituire altri valori NTSTATUS.
Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.
Commenti
Usare WdfUsbTargetDeviceFormatRequestForUrb, seguito da WdfRequestSend, per inviare una richiesta di trasferimento del controllo USB in modo sincrono o asincrono. In alternativa, usare il metodo WdfUsbTargetDeviceSendUrbSynchronously per inviare una richiesta in modo sincrono.
È possibile inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O oppure creare e inviare una nuova richiesta.
Per inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O, specificare l'handle della richiesta ricevuta per il parametro Request del metodo WdfUsbTargetDeviceFormatRequestForUrb.
Per creare una nuova richiesta di I/O, chiamare WdfRequestCreate per preallocare un oggetto richiesta. Specificare l'handle di richiesta per il parametro Request del metodo WdfUsbTargetDeviceFormatRequestForUrb. È possibile riutilizzare l'oggetto richiesta chiamando WdfRequestReuse. La funzione di callback EvtDriverDeviceAdd del driver può preallocare oggetti richiesta per un dispositivo.
Dopo aver chiamato WdfUsbTargetDeviceFormatRequestForUrb per formattare una richiesta di I/O, il driver deve chiamare WdfRequestSend per inviare la richiesta (in modo sincrono o asincrono) a una destinazione di I/O. Non usare l'opzione send and forget per inviare la richiesta.
Più chiamate a WdfUsbTargetDeviceFormatRequestForUrb che usano la stessa richiesta non causano allocazioni di risorse aggiuntive. Pertanto, per ridurre la probabilità che WdfRequestCreate restituisca STATUS_INSUFFICIENT_RESOURCES, la funzione di callback EvtDriverDeviceAdd del driver può chiamare WdfRequestCreate per preallocare uno o più oggetti richiesta per un dispositivo. Il driver può successivamente riutilizzare (chiamare WdfRequestReuse), riformattare (chiamare WdfUsbTargetDeviceFormatRequestForUrb) e inviare nuovamente (chiamare WdfRequestSend) ogni oggetto richiesta senza rischiare un valore restituito STATUS_INSUFFICIENT_RESOURCES da una chiamata successiva a WdfRequestCreate. Tutte le chiamate successive a WdfUsbTargetDeviceFormatRequestForUrb per l'oggetto richiesta riutilizzato restituiranno STATUS_SUCCESS, se i valori dei parametri non cambiano. Se il driver non chiama lo stesso metodo di formattazione delle richieste ogni volta, è possibile allocare risorse aggiuntive.
Per informazioni su come ottenere informazioni sullo stato dopo il completamento di una richiesta di I/O, vedere Ottenere informazioni di completamento.
Per altre informazioni sul metodo WdfUsbTargetDeviceFormatRequestForUrb e sulle destinazioni di I/O USB, vedere Destinazioni di I/O USB.
Esempio
Nell'esempio di codice riportato di seguito viene creato un oggetto memoria per contenere unastrutturaae, inizializza la struttura RPC e viene chiamato WdfUsbTargetDeviceFormatRequestForUrb per formattare una richiesta che utilizza il contenuto della struttura RPC. L'esempio registra quindi una funzione di callback CompletionRoutine e invia la richiesta a una destinazione di I/O.
WDFMEMORY urbMemory;
URB *urbBuffer;
status = WdfMemoryCreate(
WDF_NO_OBJECT_ATTRIBUTES,
NonPagedPool,
0,
sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST),
&urbMemory,
NULL
);
if (!NT_SUCCESS(status)){
return status;
}
urbBuffer = (PURB) WdfMemoryGetBuffer(
urbMemory,
NULL
);
urbBuffer->UrbHeader.Function = URB_FUNCTION_GET_CONFIGURATION;
urbBuffer->UrbHeader.Length = sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST);
urbBuffer->UrbControlGetConfigurationRequest.TransferBufferLength = 1 ;
urbBuffer->UrbControlGetConfigurationRequest.TransferBufferMDL = NULL;
urbBuffer->UrbControlGetConfigurationRequest.TransferBuffer = outBuffer;
urbBuffer->UrbControlGetConfigurationRequest.UrbLink = NULL;
status = WdfUsbTargetDeviceFormatRequestForUrb(
deviceContext->WdfUsbTargetDevice,
request,
urbMemory,
NULL
);
WdfRequestSetCompletionRoutine(
request,
MyCompletionRoutine,
NULL);
if (WdfRequestSend(
request,
WdfUsbTargetDeviceGetIoTarget(UsbDevice),
NULL
) == FALSE) {
status = WdfRequestGetStatus(request);
}
Requisiti
| Requisito | Valore |
|---|---|
| Piattaforma di destinazione | Universale |
| Versione KMDF minima | 1.0 |
| 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), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |