Funzione WdfUsbTargetDeviceSendControlTransferSynchronously (wdfusb.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfUsbTargetDeviceSendControlTransferSynchronously compila una richiesta di trasferimento del controllo USB e la invia in modo sincrono a una destinazione di I/O.

Sintassi

NTSTATUS WdfUsbTargetDeviceSendControlTransferSynchronously(
  [in]            WDFUSBDEVICE                  UsbDevice,
  [in, optional]  WDFREQUEST                    Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS     RequestOptions,
  [in]            PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR        MemoryDescriptor,
  [out, optional] PULONG                        BytesTransferred
);

Parametri

[in] UsbDevice

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

[in, optional] Request

Handle per un oggetto richiesta del framework. Questo parametro è facoltativo e può essere NULL. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in, optional] RequestOptions

Puntatore a una struttura WDF_REQUEST_SEND_OPTIONS allocata dal chiamante che specifica le opzioni per la richiesta. Questo puntatore è facoltativo e può essere NULL. 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] MemoryDescriptor

Puntatore a una struttura di WDF_MEMORY_DESCRIPTOR allocata dal chiamante 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.

[out, optional] BytesTransferred

Puntatore a una posizione che riceve il numero di byte trasferiti. Questo parametro è facoltativo e può essere NULL.

Valore restituito

WdfUsbTargetDeviceSendControlTransferSynchronously restituisce il valore di stato di completamento della destinazione di I/O 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_INSUFFICIENT_RESOURCES	Memoria insufficiente disponibile.
STATUS_INVALID_DEVICE_REQUEST	È stato specificato un descrittore di memoria non valido oppure la richiesta di I/O specificata è già stata accodata a una destinazione di I/O.
STATUS_IO_TIMEOUT	Il driver ha fornito un valore di timeout e la richiesta non è stata completata entro il tempo assegnato.

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 il metodo WdfUsbTargetDeviceSendControlTransferSynchronously per inviare in modo sincrono una richiesta di trasferimento del controllo USB. Per inviare tali richieste in modo asincrono, usare WdfUsbTargetDeviceFormatRequestForControlTransfer, seguito da WdfRequestSend.

Il metodo WdfUsbTargetDeviceSendControlTransferSynchronously non restituisce fino al completamento della richiesta, a meno che il driver non fornisca un valore di timeout nella struttura WDF_REQUEST_SEND_OPTIONS a cui punta il parametro RequestOptions o a meno che non venga rilevato un errore.

È 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 .
Usare il buffer di input o output della richiesta ricevuta per il parametro MemoryDescriptor .
Il driver può chiamare WdfRequestRetrieveInputMemory o WdfRequestRetrieveOutputMemory per ottenere un handle a un oggetto memoria del framework che rappresenta l'input o il buffer di output della richiesta e quindi posizionare tale handle nella struttura WDF_MEMORY_DESCRIPTOR fornita dal driver per il parametro MemoryDescriptor .

Per creare e inviare una nuova richiesta:

Specificare un handle di richiesta NULL nel parametro Request oppure creare un nuovo oggetto richiesta e fornire il relativo handle:
- Se si specifica un handle di richiesta NULL , il framework usa un oggetto richiesta interno. Questa tecnica è semplice da usare, ma il driver non può annullare la richiesta.
- Se chiami WdfRequestCreate per creare uno o più oggetti richiesta, puoi riutilizzare questi oggetti richiesta chiamando WdfRequestReuse. Questa tecnica consente alla funzione di callback EvtDriverDeviceAdd del driver di preallocare gli oggetti richiesta per un dispositivo. Inoltre, un altro thread del driver può chiamare WdfRequestCancelSentRequest per annullare la richiesta, se necessario.
Il driver può specificare un parametro RequestOptions diverso da NULL, indipendentemente dal fatto che il driver fornisca un parametro non NULL o nullRequest. È ad esempio possibile usare il parametro RequestOptions per specificare un valore di timeout.
Fornire spazio buffer per il parametro MemoryDescriptor del metodo WdfUsbTargetDeviceSendControlTransferSynchronously.
Il driver può specificare questo spazio buffer come buffer allocato in locale, come handle WDFMEMORY o come MDL. È possibile usare qualsiasi metodo sia più pratico.

Se necessario, il framework converte la descrizione del buffer in quella corretta per il metodo della destinazione di I/O per l'accesso ai buffer di dati.

Sono disponibili le tecniche seguenti:
- Specificare un buffer locale
  Poiché WdfUsbTargetDeviceSendControlTransferSynchronously gestisce le richieste di I/O in modo sincrono, il driver può creare buffer di richiesta locali per la routine chiamante, come illustrato nell'esempio di codice seguente.
```
WDF_MEMORY_DESCRIPTOR  memoryDescriptor;
MY_BUFFER_TYPE  myBuffer;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor,
                                  (PVOID) &myBuffer,
                                  sizeof(myBuffer));
```
- Fornire un handle WDFMEMORY
  Chiamare WdfMemoryCreate o WdfMemoryCreatePreallocated per ottenere un handle per la memoria gestita dal framework, come illustrato nell'esempio di codice seguente.
```
WDF_MEMORY_DESCRIPTOR  memoryDescriptor;
WDFMEMORY  memoryHandle = NULL;
status = WdfMemoryCreate(NULL,
                         NonPagedPool,
                         POOL_TAG,
                         MY_BUFFER_SIZE,
                         &memoryHandle,
                         NULL);
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&memoryDescriptor,
                                  memoryHandle,
                                  NULL);
```
  In alternativa, il driver può chiamare WdfRequestRetrieveInputMemory o WdfRequestRetrieveOutputMemory per ottenere un handle a un oggetto memoria framework che rappresenta il buffer della richiesta di I/O ricevuta, se si vuole che il driver passi il contenuto del buffer alla destinazione di I/O. Il driver non deve completare la richiesta di I/O ricevuta finché la nuova richiesta inviata da WdfUsbTargetDeviceSendControlTransferSynchronously alla destinazione di I/O è stata eliminata, riutilizzata o riformattata. WdfUsbTargetDeviceSendControlTransferSynchronously incrementa il conteggio dei riferimenti dell'oggetto memoria. L'eliminazione, il riutilizzo o la riformattazione di un oggetto richiesta decrementa il conteggio dei riferimenti dell'oggetto memoria.
- Specificare un MDL
  I driver possono ottenere mdls associati a una richiesta di I/O ricevuta chiamando WdfRequestRetrieveInputWdmMdl o WdfRequestRetrieveOutputWdmMdl.

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 WdfUsbTargetDeviceSendControlTransferSynchronously e sulle destinazioni di I/O USB, vedi Destinazioni di I/O USB.

Esempio

L'esempio di codice seguente inizializza una struttura WDF_USB_CONTROL_SETUP_PACKET e quindi chiama WdfUsbTargetDeviceSendControlTransferSynchronously per inviare un trasferimento di controllo specifico del fornitore.

WDF_USB_CONTROL_SETUP_PACKET  controlSetupPacket;

WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(
                                         &controlSetupPacket,
                                         BmRequestHostToDevice,
                                         BmRequestToDevice,
                                         USBFX2LK_REENUMERATE,
                                         0,
                                         0
                                         );

status = WdfUsbTargetDeviceSendControlTransferSynchronously(
                                         UsbDevice,
                                         WDF_NO_HANDLE,
                                         NULL,
                                         &controlSetupPacket,
                                         NULL,
                                         NULL
                                         );
return status;

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	PASSIVE_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestForUrbXrb(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)