Funzione IoGetDeviceInterfaces (wdm.h)

Articolo
02/27/2024

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 limita la ricerca solo alle istanze dell'interfaccia del dispositivo rappresentate dall'oggetto PDO.

[in] Flags

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

Contrassegno	Significato
DEVICE_INTERFACE_INCLUDE_NONACTIVE	Restituisce istanze dell'interfaccia dispositivo disabilitate oltre alle istanze dell'interfaccia abilitate.

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

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

[out] SymbolicLinkList

Puntatore a un puntatore a un puntatore a caratteri wide a cui la routine, se ha esito positivo, scrive l'indirizzo di base di un buffer che contiene 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 è terminata con null; la fine dell'intero elenco è contrassegnata da un carattere Null aggiuntivo. La routine alloca il buffer per queste stringhe dalla memoria del sistema a pagina. Il chiamante è responsabile della liberazione del buffer (chiamando la routine ExFreePool ) quando non è più necessario.

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 esito positivo. I valori restituiti degli errori possibili includono quanto segue.

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

Commenti

IoGetDeviceInterfaces restituisce un elenco di istanze dell'interfaccia del dispositivo corrispondenti ai criteri di ricerca. Un componente in modalità kernel chiama in genere questa routine per ottenere un elenco di tutte le istanze dell'interfaccia 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 a oggetti 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 del dispositivo richiesta, è elencata prima in SimbolicLinkList. 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 sono abilitate altre istanze dell'interfaccia del dispositivo di una determinata classe nel sistema, registrare 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.

Requisiti

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	HwStorPortProhibitedDDDIs(storport), MarkPower(wdm), MarkPowerDown (wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)