Función IoSetDeviceInterfaceState (wdm.h)

Artículo
08/08/2023

La rutina IoSetDeviceInterfaceState habilita o deshabilita una instancia de una clase de interfaz de dispositivo registrada anteriormente.

Sintaxis

NTSTATUS IoSetDeviceInterfaceState(
  [in] PUNICODE_STRING SymbolicLinkName,
  [in] BOOLEAN         Enable
);

Parámetros

[in] SymbolicLinkName

Puntero a una cadena que identifica la instancia de interfaz de dispositivo que se está habilitando o deshabilitando. Esta cadena se obtuvo de una llamada anterior a IoRegisterDeviceInterface o IoGetDeviceInterfaces.

[in] Enable

TRUE indica que se está habilitando la interfaz del dispositivo. FALSE indica que la interfaz del dispositivo se está deshabilitando.

Valor devuelto

IoSetDeviceInterfaceState devuelve STATUS_SUCCESS si la llamada se realizó correctamente. Esta rutina devuelve un estado informativo de STATUS_OBJECT_NAME_EXISTS si el autor de la llamada solicitó habilitar una interfaz de dispositivo que ya estaba habilitada. Los posibles valores devueltos de error se describen a continuación.

Código devuelto	Descripción
STATUS_OBJECT_NAME_NOT_FOUND	El autor de la llamada intentó deshabilitar una interfaz de dispositivo que no estaba habilitada.

Comentarios

IoSetDeviceInterfaceState habilita una instancia de una interfaz de dispositivo registrada para su uso por parte de aplicaciones y otros componentes del sistema. La clase de interfaz debe haberse registrado previamente con IoRegisterDeviceInterface o desde el modo de usuario.

Las aplicaciones y otros componentes del sistema solo pueden abrir interfaces habilitadas.

Una función o un controlador de filtro normalmente llama a esta rutina con Enable establecido en TRUE después de iniciar correctamente un dispositivo en respuesta a un IRP de IRP_MN_START_DEVICE . Este controlador debe deshabilitar la instancia de interfaz de dispositivo (es decir, llame a IoSetDeviceInterfaceState y establezca Habilitar en FALSE) cuando quite el dispositivo en respuesta a un IRP de IRP_MN_REMOVE_DEVICE o un IRP IRP_MN_SURPRISE_REMOVAL . Si un controlador no deshabilita una interfaz de dispositivo cuando procesa estos IRP de eliminación, el controlador no debe intentar hacerlo posteriormente porque el administrador de PnP deshabilitará la interfaz cuando el administrador de PnP quite el dispositivo.

Si un dispositivo se quita repentinamente (por ejemplo, mediante una eliminación sorpresa), pero sigue teniendo una instancia de interfaz de dispositivo válida, se producirá un problema si el dispositivo se vuelve a adjuntar. Este problema se produce cuando el administrador de PnP enumera el dispositivo recién conectado y habilita una instancia de interfaz de dispositivo, que existirá en la misma ruta de acceso del Registro que la instancia de interfaz de dispositivo existente.

Tenga en cuenta que si el controlador llama a IoSetDeviceInterfaceState para deshabilitar una instancia de interfaz de dispositivo en respuesta a un IRP de IRP_MN_SURPRISE_REMOVAL , el controlador no debe intentar deshabilitar la misma instancia de interfaz de dispositivo en respuesta a un IRP de IRP_MN_REMOVE_DEVICE .

Si una llamada a IoSetDeviceInterfaceState expone correctamente una instancia de interfaz de dispositivo, el sistema notifica a los componentes registrados para la notificación PnP de un cambio de clase de dispositivo. Del mismo modo, si una llamada a esta rutina deshabilita una instancia de interfaz de dispositivo existente, el sistema envía las notificaciones adecuadas.

El administrador de PnP no envía notificaciones de llegadas de instancias de interfaz hasta que se complete el IRP_MN_START_DEVICE IRP, lo que indica que todos los controladores del dispositivo han completado sus operaciones de inicio. Además, el administrador de PnP produce un error al crear solicitudes para el dispositivo hasta que se complete el irP de IRP_MN_START_DEVICE .

Los autores de llamadas de IoSetDeviceInterfaceState 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), IrqlIoPassive1(wdm), LowerDriverReturn(wdm), PowerIrpDDis(wdm)