Función IoGetDeviceInterfaces (wdm.h)

Artículo
08/08/2023

La rutina IoGetDeviceInterfaces devuelve una lista de instancias de interfaz de dispositivo de una clase de interfaz de dispositivo determinada (como todos los dispositivos del sistema que admiten una interfaz HID).

Sintaxis

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

Parámetros

[in] InterfaceClassGuid

Puntero a un GUID de clase que especifica la clase de interfaz de dispositivo. Los GUID de una clase deben estar en un archivo de encabezado específico del dispositivo.

[in, optional] PhysicalDeviceObject

Puntero a un PDO opcional que limita la búsqueda solo a las instancias de interfaz de dispositivo del dispositivo representadas por el PDO.

[in] Flags

Especifica marcas que modifican la búsqueda de interfaces de dispositivo. Actualmente solo se define una marca y se describe en la tabla siguiente.

Marca	Significado
DEVICE_INTERFACE_INCLUDE_NONACTIVE	Devuelve instancias de interfaz de dispositivo deshabilitadas además de las instancias de interfaz habilitadas.

Al buscar un dispositivo que admita una clase de interfaz determinada, el autor de la llamada requiere una instancia de interfaz habilitada y, por tanto, no establece la marca DEVICE_INTERFACE_INCLUDE_NONACTIVE.

Normalmente, un controlador establece la marca DEVICE_INTERFACE_INCLUDE_NONACTIVE para buscar las instancias de interfaz deshabilitadas que el controlador debe habilitar. Por ejemplo, el archivo INF podría haber dirigido el instalador de clase para el dispositivo para registrar una o varias instancias de interfaz para el dispositivo. Las instancias de interfaz se registrarían, pero no se pueden usar hasta que el controlador las habilite (mediante IoSetDeviceInterfaceState). Para restringir la lista de instancias de interfaz devueltas solo a las expuestas por un dispositivo determinado, un controlador puede especificar physicalDeviceObject.

[out] SymbolicLinkList

Puntero a un puntero de caracteres anchos al que la rutina, si se ejecuta correctamente, escribe la dirección base de un búfer que contiene una lista de cadenas Unicode. Estas cadenas son nombres de vínculo simbólicos que identifican las instancias de la interfaz de dispositivo que coinciden con los criterios de búsqueda. Cada cadena Unicode de la lista termina en null; El final de toda la lista está marcado por un carácter null adicional. La rutina asigna el búfer para estas cadenas de la memoria paginada del sistema. El autor de la llamada es responsable de liberar el búfer (llamando a la rutina ExFreePool ) cuando ya no es necesario.

Si ninguna instancia de interfaz de dispositivo coincide con los criterios de búsqueda, esta rutina devuelve STATUS_SUCCESS y la cadena contiene un solo carácter NULL.

Valor devuelto

IoGetDeviceInterfaces devuelve STATUS_SUCCESS si la llamada se realizó correctamente. Entre los posibles valores devueltos de error se incluyen los siguientes.

Código devuelto	Descripción
STATUS_INVALID_DEVICE_REQUEST	Posiblemente indica que PhysicalDeviceObject no era un puntero PDO válido.

Comentarios

IoGetDeviceInterfaces devuelve una lista de instancias de interfaz de dispositivo que coinciden con los criterios de búsqueda. Normalmente, un componente en modo kernel llama a esta rutina para obtener una lista de todas las instancias de interfaz de dispositivo habilitadas de una clase de interfaz de dispositivo determinada. Este componente puede obtener un puntero al objeto de archivo o al objeto de dispositivo de una interfaz llamando a la rutina IoGetDeviceObjectPointer o ZwCreateFile . El puntero de objeto de dispositivo devuelto por IoGetDeviceObjectPointer apunta a la parte superior de la pila de dispositivos del dispositivo y se puede usar en llamadas a la rutina IoCallDriver .

Si hay una interfaz predeterminada para la clase de interfaz de dispositivo solicitada, aparece primero en SymbolicLinkList. Las interfaces predeterminadas se pueden establecer en modo de usuario, pero no en modo kernel.

El formato de un nombre de vínculo simbólico es opaco; el autor de la llamada no debe intentar analizar un nombre de vínculo simbólico.

Los vínculos simbólicos para las instancias de interfaz de dispositivo se pueden usar en los arranques del sistema.

Para recibir notificaciones cuando se habilitan instancias de interfaz de dispositivo adicionales de una clase determinada en el sistema, regístrese para recibir notificaciones de un cambio de clase de dispositivo mediante una llamada a la rutina IoRegisterPlugPlayNotification .

Los autores de llamadas de IoGetDeviceInterfaces deben ejecutarse en IRQL = PASSIVE_LEVEL en el contexto de un subproceso del sistema.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible a partir de Windows 2000.
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte la sección Comentarios)
Reglas de cumplimiento de DDI	HwStorPortProhibitedDDIs(storport), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)