IOCTL_USB_GET_PORT_CONNECTOR_PROPERTIES IOCTL (usbioctl.h)
La richiesta di controllo I/O IOCTL_USB_GET_PORT_CONNECTOR_PROPERTIES viene inviata da un'applicazione per recuperare informazioni su una porta specifica in un hub USB.
IOCTL_USB_GET_PORT_CONNECTOR_PROPERTIES è una richiesta di controllo I/O in modalità utente. Questa richiesta è destinata al dispositivo hub USB (Universal Serial Bus) (GUID_DEVINTERFACE_USB_HUB).
Codice principale
Buffer di input
AssociatedIrp.SystemBuffer punta a una struttura di USB_PORT_CONNECTOR_PROPERTIES allocata dal chiamante. Il chiamante deve impostare i membri della struttura come segue:
- Il chiamante deve specificare il numero di porta della porta sottoposta a query nel membro ConnectionIndex. ConnectionIndex deve essere un valore compreso nell'intervallo da 1 a n, dove n è il numero di porta più alto recuperato in una richiesta di controllo di I/O IOCTL_USB_GET_HUB_INFORMATION_EX precedente.
-
Il chiamante deve specificare il membro CompanionIndex. Per un hub SuperSpeed, il chiamante deve impostare il membro CompanionIndex su 0.
Il chiamante può usare CompanionIndex per ottenere i numeri di porta associati alla porta su cui viene eseguita la query. Se alla porta sono associate più porte complementari, per ottenere tutti i numeri di porta, l'applicazione può inviare la richiesta in un ciclo. Iniziare con CompanionIndex impostato su 0 e incrementare il valore CompanionIndex in ogni iterazione fino al completamento della richiesta con CompanionPortNumber impostato su 0 e CompanionHubSymbolicLinkName è NULL.
Lunghezza del buffer di input
Il membro Parameters.DeviceIoControl.InputBufferLength indica le dimensioni, in byte, del buffer allocato dal chiamante a cui punta AssociatedIrp.SystemBuffer. Per altre informazioni, vedere Osservazioni.
Buffer di output
Nell'output USB_PORT_CONNECTOR_PROPERTIES, a cui punta AssociatedIrp.SystemBuffer, viene compilato con informazioni sul connettore fisico associato alla porta.
Lunghezza del buffer di output
Il membro Parameters.DeviceIoControl.OutputBufferLength indica le dimensioni, in byte, del buffer di output SystemBuffer.
Blocco di stato
Lo stack USB imposta Irp->IoStatus.Status su STATUS_SUCCESS se la richiesta ha esito positivo. In caso contrario, lo stack USB imposta Stato sulla condizione di errore appropriata, ad esempio STATUS_INVALID_PARAMETER o STATUS_INSUFFICIENT_RESOURCES. Se l'hub non è stato avviato o non è funzionante, la richiesta restituisce STATUS_UNSUCCESSFUL.
Osservazioni
Il chiamante deve fornire un buffer sufficientemente grande da contenere una struttura USB_PORT_CONNECTOR_PROPERTIES e il nome di collegamento simbolico di un hub complementare, se tale hub è associato alla porta specificata. Per ottenere le dimensioni del buffer da allocare, il chiamante deve inviare una richiesta di IOCTL_USB_GET_PORT_CONNECTOR_PROPERTIES. Nella richiesta AssociatedIrp.SystemBuffer deve essere una struttura USB_PORT_CONNECTOR_PROPERTIES allocata dal chiamante e Parameters.DeviceIoControl.InputBufferLength deve essere sizeof(USB_PORT_CONNECTOR_PROPERTIES). Al termine, il USB_PORT_CONNECTOR_PROPERTIES membro ActualLength indica le dimensioni effettive del buffer. Se esiste un nome di collegamento simbolico, il valore ricevuto include le dimensioni della stringa in cui è archiviato il nome del collegamento.
In base al valore actualLength, il chiamante può quindi allocare un buffer e inviare nuovamente la richiesta di IOCTL_USB_GET_PORT_CONNECTOR_PROPERTIES. Al termine della richiesta, il buffer viene riempito con informazioni sulla porta e il membro CompanionHubSymbolicLinkName è una stringa Unicode che contiene il nome simbolico del collegamento dell'hub complementare.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows 8 |
| server minimo supportato | Nessuna supportata |
| intestazione | usbioctl.h (include Usbioctl.h) |