struttura _URB_CONTROL_TRANSFER_EX (usb.h)

Articolo
02/29/2024

La struttura _URB_CONTROL_TRANSFER_EX viene usata dai driver client USB per trasferire dati da o verso una pipe di controllo, con un timeout che limita il tempo di trasferimento accettabile.

Sintassi

struct _URB_CONTROL_TRANSFER_EX {
  struct _URB_HEADER   Hdr;
  USBD_PIPE_HANDLE     PipeHandle;
  ULONG                TransferFlags;
  ULONG                TransferBufferLength;
  PVOID                TransferBuffer;
  PMDL                 TransferBufferMDL;
  ULONG                Timeout;
  ULONG                Pad;
  struct _URB_HCD_AREA hca;
  UCHAR                SetupPacket[8];
};

Members

Hdr

Puntatore a una struttura di _URB_HEADER che specifica le informazioni sull'intestazione HEADER. Hdr.Function deve essere URB_FUNCTION_CONTROL_TRANSFER_EX e Hdr.Length deve essere sizeof(_URB_CONTROL_TRANSFER_EX).

PipeHandle

Handle per la pipe.

Se target è l'endpoint di controllo predefinito, PipeHandle deve essere NULL. In questo caso, transferFlags deve contenere il flag USBD_DEFAULT_PIPE_TRANSFER.

Se target è un endpoint di controllo non predefinito, PipeHandle specifica un handle opaco per la pipe di controllo. Il driver del controller host restituisce questo handle quando il driver client seleziona la configurazione del dispositivo con un URB_FUNCTION_SELECT_CONFIGURATION di tipo o quando il driver client modifica le impostazioni per un'interfaccia con un URB_FUNCTION_SELECT_INTERFACE di tipo".

TransferFlags

Specifica zero, uno o una combinazione dei flag seguenti:

Valore	Significato
USBD_TRANSFER_DIRECTION_IN	È impostato per richiedere i dati da un dispositivo. Per trasferire i dati in un dispositivo, questo flag deve essere chiaro.
USBD_TRANSFER_DIRECTION_OUT	È impostato per trasferire i dati in un dispositivo. L'impostazione di questo flag equivale alla cancellazione del flag di USBD_TRANSFER_DIRECTION_IN.
USBD_SHORT_TRANSFER_OK	È impostato per indirizzare il controller host a non restituire un errore quando riceve un pacchetto dal dispositivo che è più breve della dimensione massima del pacchetto per l'endpoint. Le dimensioni massime dei pacchetti per l'endpoint vengono segnalate nel membro bMaxPacketSize0 della struttura di USB_DEVICE_DESCRIPTOR (descrittore di dispositivo) per l'endpoint di controllo predefinito. Per un endpoint di controllo non predefinito, le dimensioni massime dei pacchetti sono impostate nel membro wMaxPacketSize della struttura di USB_ENDPOINT_DESCRIPTOR (descrittore di endpoint). Quando il controller host riceve un pacchetto la cui lunghezza è più breve del valore wMaxPacketSize in un endpoint di controllo, il comportamento è il seguente a seconda del tipo di controller host: Nei controller host EHCI il controller host procede immediatamente alla fase di stato del trasferimento del controllo. Il trasferimento viene completato correttamente, indipendentemente dal fatto che USBD_SHORT_TRANSFER_OK sia impostato. Nei controller host UHCI e OHCI, se USBD_SHORT_TRANSFER_OK è impostato, il controller host procede alla fase di stato. Se USBD_SHORT_TRANSFER_OK non è impostato, il controller host abbandona i dati e le fasi di stato del trasferimento del controllo e il trasferimento viene completato con un errore.
USBD_DEFAULT_PIPE_TRANSFER	È impostato per indirizzare il controller host a eseguire un trasferimento di controllo sulla pipe di controllo predefinita. In questo modo il chiamante può inviare comandi alla pipe di controllo predefinita senza specificare in modo esplicito l'handle della pipe.

TransferBufferLength

Specifica la lunghezza, in byte, del buffer specificato in TransferBuffer o descritto in TransferBufferMDL. Il driver del controller host restituisce il numero di byte inviati o letti dalla pipe in questo membro.

TransferBuffer

Puntatore a un buffer residente per il trasferimento o è NULL se viene fornito un MDL in TransferBufferMDL. Il contenuto di questo buffer dipende dal valore di TransferFlags. Se viene specificato USBD_TRANSFER_DIRECTION_IN questo buffer conterrà i dati letti dal dispositivo al ritorno dal driver del controller host. In caso contrario, questo buffer contiene i dati forniti dal driver per il trasferimento al dispositivo.

TransferBufferMDL

Puntatore a un MDL che descrive un buffer residente o è NULL se viene fornito un buffer in TransferBuffer. Il contenuto del buffer dipende dal valore di TransferFlags. Se viene specificato USBD_TRANSFER_DIRECTION_IN, il buffer descritto conterrà i dati letti dal dispositivo al ritorno dal driver del controller host. In caso contrario, il buffer contiene i dati forniti dal driver per il trasferimento al dispositivo. Questo file MDL deve essere allocato da un pool non di paging.

Timeout

Indica il tempo, espresso in millisecondi, prima del timeout dell'OGGETTO. Un valore pari a 0 indica che non è presente alcun timeout per questo ARGOMENTO.

Pad

Riservato. Non usare.

hca

Riservato. Non usare.

SetupPacket[8]

Specifica un pacchetto di installazione della richiesta definito da USB. Il formato di un pacchetto di configurazione della richiesta USB è disponibile nella specifica usb core.

Commenti

Questa struttura DELL'OGGETTO è identica a _URB_CONTROL_TRANSFER, ad eccezione del fatto che il membro Timeout stabilisce un timeout per l'oggetto TYPE.

I membri riservati di questa struttura devono essere considerati opachi e sono riservati per l'uso del sistema.