Funzione WdfUsbTargetDeviceFormatRequestForControlTransfer (wdfusb.h)
[Si applica a KMDF e UMDF]
Il metodo WdfUsbTargetDeviceFormatRequestForControlTransfer compila una richiesta di trasferimento del controllo USB, ma non invia la richiesta.
Sintassi
NTSTATUS WdfUsbTargetDeviceFormatRequestForControlTransfer(
[in] WDFUSBDEVICE UsbDevice,
[in] WDFREQUEST Request,
[in] PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
[in, optional] WDFMEMORY TransferMemory,
[in, optional] PWDFMEMORY_OFFSET TransferOffset
);
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] SetupPacket
Puntatore a una struttura WDF_USB_CONTROL_SETUP_PACKET allocata dal chiamante che descrive il trasferimento del controllo.
[in, optional] TransferMemory
Handle per un oggetto memoria del framework che descrive un input o un buffer di output, a seconda del comando specifico del dispositivo. Questo puntatore è facoltativo e può essere NULL. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
[in, optional] TransferOffset
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 e la lunghezza, all'interno del buffer specificato da TransferMemory . Se questo puntatore è NULL, il framework usa l'intero buffer.
Valore restituito
WdfUsbTargetDeviceFormatRequestForControlTransfer 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 disponibile. |
|
È stato specificato un descrittore di memoria non valido oppure la richiesta di I/O specificata è già stata accodata a una destinazione di I/O. |
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 WdfUsbTargetDeviceFormatRequestForControlTransfer, seguito da WdfRequestSend, per inviare una richiesta di trasferimento del controllo USB in modo sincrono o asincrono. In alternativa, usare il metodo WdfUsbTargetDeviceSendControlTransferSynchronously 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. In entrambi i casi, il framework richiede un oggetto richiesta e, a seconda del tipo di trasferimento del controllo, possibilmente di spazio buffer.
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 Request WdfUsbTargetDeviceFormatRequestForControlTransfer.
-
Usare il buffer di input o output della richiesta ricevuta per il parametro TransferMemory .
Il driver deve chiamare WdfRequestRetrieveInputMemory o WdfRequestRetrieveOutputMemory per ottenere un handle a un oggetto memoria framework che rappresenta il buffer di input o output della richiesta e usare tale handle come valore per TransferMemory.
-
Creare un nuovo oggetto richiesta e specificare il relativo handle per il parametro Request del metodo WdfUsbTargetDeviceFormatRequestForControlTransfer.
Chiamare WdfRequestCreate per preallocare uno o più oggetti richiesta. È possibile riutilizzare questi oggetti richiesta chiamando WdfRequestReuse. La funzione di callback EvtDriverDeviceAdd del driver può preallocare oggetti richiesta per un dispositivo.
-
Specificare lo spazio del buffer e specificare l'handle del buffer per il parametro TransferMemory del metodo WdfUsbTargetDeviceFormatRequestForControlTransfer.
Il driver deve specificare questo spazio buffer come handle WDFMEMORY per la memoria gestita dal framework. Il driver può eseguire una delle operazioni seguenti:
- Chiamare WdfMemoryCreate o WdfMemoryCreatePreallocated per creare un nuovo buffer di memoria, se si vuole che il driver passi un nuovo buffer alla destinazione di I/O.
- Chiamare WdfRequestRetrieveInputMemory o WdfRequestRetrieveOutputMemory per ottenere un handle per l'oggetto memoria che rappresenta il buffer di una richiesta di I/O ricevuta, se si desidera che il driver passi il contenuto del buffer alla destinazione di I/O.
Più chiamate a WdfUsbTargetDeviceFormatRequestForControlTransfer 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 WdfUsbTargetDeviceFormatRequestForControlTransfer) 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 WdfUsbTargetDeviceFormatRequestForControlTransfer 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.
Il framework imposta il flag di USBD_SHORT_TRANSFER_OK nel relativo RIQUADRO interno. L'impostazione di questo flag consente all'ultimo pacchetto di un trasferimento dati di essere inferiore alla dimensione massima del pacchetto.
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 WdfUsbTargetDeviceFormatRequestForControlTransfer e sulle destinazioni di I/O USB, vedi Destinazioni di I/O USB.
Esempio
Nell'esempio di codice seguente viene creato un oggetto richiesta e un oggetto memory e quindi viene inizializzata una struttura WDF_USB_CONTROL_SETUP_PACKET per il trasferimento di un controllo "get status". L'esempio chiama quindi WdfUsbTargetDeviceFormatRequestForControlTransfer per formattare la richiesta. L'esempio imposta quindi una funzione di callback CompletionRoutine e invia la richiesta a una destinazione di I/O.
WDF_USB_CONTROL_SETUP_PACKET packet;
NTSTATUS status;
WDF_OBJECT_ATTRIBUTES attributes;
WDFMEMORY memHandle;
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
status = WdfRequestCreate(
&attributes,
WdfUsbTargetDeviceGetIoTarget(
UsbTargetDevice,
&request
)
);
if (!NT_SUCCESS(status)){
return status;
}
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = request;
status = WdfMemoryCreate(
&attributes,
NonPagedPool,
0,
sizeof(USHORT),
&memHandle,
NULL
);
if (!NT_SUCCESS(status)){
return status;
}
WDF_USB_CONTROL_SETUP_PACKET_INIT_GET_STATUS(
&packet,
BmRequestToDevice,
0
);
status = WdfUsbTargetDeviceFormatRequestForControlTransfer(
UsbTargetDevice,
request,
&packet,
memHandle,
NULL
);
if (!NT_SUCCESS(status)){
return status;
}
WdfRequestSetCompletionRoutine(
request,
MyCompletionRoutine,
NULL
);
if (WdfRequestSend(
request,
WdfUsbTargetDeviceGetIoTarget(UsbTargetDevice),
NULL
) == FALSE) {
status = WdfRequestGetStatus(request);
}
Requisiti
| Requisito | Valore |
|---|---|
| Piattaforma di destinazione | Universale |
| Versione KMDF minima | 1.0 |
| Versione UMDF minima | 2,0 |
| Intestazione | wdfusb.h (include Wdfusb.h) |
| Libreria | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| Regole di conformità DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |