funzione WinUsb_ControlTransfer (winusb.h)

Articolo
08/27/2023

La funzione WinUsb_ControlTransfer trasmette i dati di controllo su un endpoint di controllo predefinito.

Sintassi

BOOL WinUsb_ControlTransfer(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            WINUSB_SETUP_PACKET     SetupPacket,
  [out]           PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

Parametri

[in] InterfaceHandle

Handle opaco per un'interfaccia nella configurazione selezionata.

Per specificare il destinatario di una richiesta di controllo come intero dispositivo o la prima interfaccia, usare l'handle restituito da WinUsb_Initialize. Per tutte le altre interfacce, ottenere l'handle per l'interfaccia di destinazione chiamando WinUsb_GetAssociatedInterface e quindi chiamare WinUsb_ControlTransfer specificando l'handle di interfaccia ottenuto.

[in] SetupPacket

Pacchetto di installazione a 8 byte di tipo WINUSB_SETUP_PACKET.

[out] Buffer

Buffer allocato dal chiamante che contiene i dati da trasferire. La lunghezza di questo buffer non deve superare i 4 KB.

[in] BufferLength

Numero di byte da trasferire, non incluso il pacchetto di installazione. Questo numero deve essere minore o uguale alla dimensione, espressa in byte, di Buffer.

[out, optional] LengthTransferred

Puntatore a una variabile ULONG che riceve il numero effettivo di byte trasferiti. Se l'applicazione non prevede il trasferimento di dati durante la fase di dati (BufferLength è zero), LengthTransferred può essere NULL.

[in, optional] Overlapped

Puntatore facoltativo a una struttura OVERLAPPED , utilizzata per le operazioni asincrone. Se questo parametro viene specificato, WinUsb_ControlTransfer restituisce immediatamente e l'evento viene segnalato al termine dell'operazione. Se La sovrapposizione non viene specificata, la funzione WinUsb_ControlTransfer trasferisce i dati in modo sincrono.

Valore restituito

WinUsb_ControlTransfer restituisce TRUE se l'operazione ha esito positivo. In caso contrario, questa routine restituisce FALSE e il chiamante può recuperare l'errore registrato chiamando GetLastError.

GetLastError può restituire uno dei codici di errore seguenti.

Codice restituito	Descrizione
ERROR_INVALID_HANDLE	Il chiamante ha passato NULL nel parametro InterfaceHandle .
ERROR_NOT_ENOUGH_MEMORY	Indica che la memoria non è sufficiente per eseguire l'operazione.

Commenti

Una richiesta di controllo viene sempre inviata dall'host all'endpoint predefinito di un dispositivo USB, ma il destinatario della richiesta può essere l'intero dispositivo, un'interfaccia o un endpoint nell'impostazione alternativa selezionata. Nella chiamata WinUsb_ControlTransfer , l'applicazione deve indicare il destinatario tramite due parametri: InterfaceHandle e SetupPacket.

Se il destinatario di una richiesta di controllo è l'intero dispositivo, la prima interfaccia o qualsiasi endpoint in tale interfaccia, l'applicazione deve usare l'handle restituito da WinUsb_Initialize. Se il destinatario è un'altra interfaccia o il relativo endpoint, l'applicazione deve ottenere l'handle WinUSB associato all'interfaccia di destinazione chiamando WinUsb_GetAssociatedInterface e quindi chiamare WinUsb_ControlTransfer specificando l'handle di interfaccia ottenuto.

In base alla sezione 9.3 della specifica USB ufficiale, il token di installazione di un trasferimento di controllo contiene informazioni sulla richiesta. Per un'applicazione WinUSB, tale token di installazione viene descritto usando la struttura WINUSB_SETUP_PACKET .

All'interno del token di installazione, i campi bmRequestType e wIndex vengono usati per indicare il destinatario della richiesta. Tali campi corrispondono rispettivamente ai membri RequestType e Index di WINUSB_SETUP_PACKET.

I due bit più bassi di RequestType indicano il destinatario della richiesta. Il destinatario può essere il dispositivo, un'interfaccia, un endpoint o un altro (per richiesta fornitore). A seconda del destinatario, il byte inferiore di Index indica l'indice definito dal dispositivo del destinatario. Il valore di Index dipende dal tipo di richiesta. Ad esempio, per le richieste di controllo standard, il valore è 0 o indica l'interfaccia o il numero di endpoint. Per determinati tipi di richieste standard, ad esempio una richiesta di GET_DESCRIPTOR per ottenere un descrittore stringa, il valore index indica l'ID lingua.

Se il destinatario è il dispositivo, l'applicazione deve impostare i valori RequestType e Index . I due bit più bassi del valore RequestType devono essere 0. Il byte inferiore del valore index dipende dal tipo di richiesta. InterfaceHandle deve essere l'handle WinUSB restituito da WinUsb_Initialize.

Se il destinatario della richiesta è un'interfaccia, l'applicazione deve impostare i due bit più bassi di RequestType su 0x01. L'applicazione non è necessaria per impostare il byte inferiore di Index per qualsiasi tipo di richiesta. Per le richieste standard, di classe e fornitore, Winusb.sys imposta il valore sul numero di interfaccia dell'interfaccia di destinazione. InterfaceHandle deve essere associato all'interfaccia di destinazione. L'applicazione può ottenere tale handle chiamando WinUsb_GetAssociatedInterface.

Se il destinatario è un endpoint, l'applicazione deve impostare i due bit più bassi di RequestType su 0x02 e un byte inferiore di Index sull'indirizzo dell'endpoint. In questo caso , InterfaceHandle è associato all'interfaccia che contiene l'endpoint. L'applicazione può ottenere tale handle chiamando WinUsb_GetAssociatedInterface.