Funzione IoGetDeviceInterfaces (wdm.h)

Articolo
02/07/2025

La routine IoGetDeviceInterfaces restituisce un elenco di istanze dell'interfaccia del dispositivo di una determinata classe di interfaccia del dispositivo, ad esempio tutti i dispositivi nel sistema che supportano un'interfaccia HID.

Sintassi

NTSTATUS IoGetDeviceInterfaces(
  [in]           const GUID     *InterfaceClassGuid,
  [in, optional] PDEVICE_OBJECT PhysicalDeviceObject,
  [in]           ULONG          Flags,
  [out]          PZZWSTR        *SymbolicLinkList
);

Parametri

[in] InterfaceClassGuid

Puntatore a un GUID di classe che specifica la classe dell'interfaccia del dispositivo. I GUID per una classe devono trovarsi in un file di intestazione specifico del dispositivo.

[in, optional] PhysicalDeviceObject

Puntatore a un PDO facoltativo che restringe la ricerca solo alle istanze dell'interfaccia del dispositivo rappresentate dal PDO.

[in] Flags

Specifica i flag che modificano la ricerca delle interfacce del dispositivo. È attualmente definito un solo flag ed è descritto nella tabella seguente.

Bandiera	Significato
DEVICE_INTERFACE_INCLUDE_NONACTIVE	Restituisce istanze dell'interfaccia del dispositivo disabilitate oltre alle istanze di interfaccia abilitate.

Quando si cerca un dispositivo che supporta una determinata classe di interfaccia, il chiamante richiede un'istanza dell'interfaccia abilitata e pertanto non imposta il flag DEVICE_INTERFACE_INCLUDE_NONACTIVE.

Un driver imposta in genere il flag DEVICE_INTERFACE_INCLUDE_NONACTIVE per individuare le istanze di interfaccia disabilitate che il driver deve abilitare. Ad esempio, il programma di installazione della classe per il dispositivo potrebbe essere stato indirizzato dal file INF per registrare una o più istanze di interfaccia per il dispositivo. Le istanze dell'interfaccia vengono registrate ma non sono utilizzabili fino a quando non sono abilitate dal driver (usando IoSetDeviceInterfaceState). Per restringere l'elenco delle istanze di interfaccia restituite solo a quelle esposte da un determinato dispositivo, un driver può specificare un PhysicalDeviceObject.

[out] SymbolicLinkList

Puntatore a un puntatore a caratteri wide a cui la routine, se ha esito positivo, scrive l'indirizzo di base di un buffer contenente un elenco di stringhe Unicode. Queste stringhe sono nomi di collegamento simbolici che identificano le istanze dell'interfaccia del dispositivo che corrispondono ai criteri di ricerca. Ogni stringa Unicode nell'elenco è con terminazione null; la fine dell'intero elenco è contrassegnata da un carattere Null aggiuntivo. La routine alloca il buffer per queste stringhe dalla memoria di sistema di paging. Il chiamante è responsabile della liberazione del buffer (chiamando la routine ExFreePool) quando non è più necessaria.

Se nessuna istanza dell'interfaccia del dispositivo corrisponde ai criteri di ricerca, questa routine restituisce STATUS_SUCCESS e la stringa contiene un singolo carattere NULL.

Valore restituito

IoGetDeviceInterfaces restituisce STATUS_SUCCESS se la chiamata ha avuto esito positivo. I valori restituiti di errore possibili includono quanto segue.

Codice restituito	Descrizione
STATUS_INVALID_DEVICE_REQUEST	Probabilmente indica che PhysicalDeviceObject non era un puntatore PDO valido.

Osservazioni

IoGetDeviceInterfaces restituisce un elenco di istanze dell'interfaccia del dispositivo che soddisfano i criteri di ricerca. Un componente in modalità kernel chiama in genere questa routine per ottenere un elenco di tutte le istanze dell'interfaccia del dispositivo abilitate di una determinata classe di interfaccia dispositivo. Tale componente può ottenere un puntatore all'oggetto file e/o all'oggetto dispositivo per un'interfaccia chiamando la routine IoGetDeviceObjectPointer o ZwCreateFile. Il puntatore all'oggetto dispositivo restituito da IoGetDeviceObjectPointer punta alla parte superiore dello stack di dispositivi per il dispositivo e può essere usato nelle chiamate alla routine IoCallDriver.

Se è presente un'interfaccia predefinita per la classe di interfaccia dispositivo richiesta, viene elencata per prima in SymbolicLinkList. Le interfacce predefinite possono essere impostate in modalità utente, ma non in modalità kernel.

Il formato di un nome di collegamento simbolico è opaco; Il chiamante non deve tentare di analizzare un nome di collegamento simbolico.

I collegamenti simbolici per le istanze dell'interfaccia del dispositivo possono essere usati tra gli avvio di sistema.

Per ricevere una notifica quando nel sistema sono abilitate istanze aggiuntive dell'interfaccia del dispositivo di una determinata classe, registrarsi per la notifica di una modifica della classe di dispositivo chiamando la routine IoRegisterPlugPlayNotification.

I chiamanti di IoGetDeviceInterfaces devono essere in esecuzione in IRQL = PASSIVE_LEVEL nel contesto di un thread di sistema.

Fabbisogno

Requisito	Valore
client minimo supportato	Disponibile a partire da Windows 2000.
piattaforma di destinazione	Universale
intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
libreria	NtosKrnl.lib
dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (vedere la sezione Osservazioni)
regole di conformità DDI	HwStorPortProhibitedDDIs(storport), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)