Função IoSetDeviceInterfaceState (wdm.h)

Artigo
08/08/2023

A rotina IoSetDeviceInterfaceState habilita ou desabilita uma instância de uma classe de interface de dispositivo registrada anteriormente.

Sintaxe

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

Parâmetros

[in] SymbolicLinkName

Ponteiro para uma cadeia de caracteres que identifica a instância da interface do dispositivo que está sendo habilitada ou desabilitada. Essa cadeia de caracteres foi obtida de uma chamada anterior para IoRegisterDeviceInterface ou IoGetDeviceInterfaces.

[in] Enable

TRUE indica que a interface do dispositivo está sendo habilitada. FALSE indica que a interface do dispositivo está sendo desabilitada.

Retornar valor

IoSetDeviceInterfaceState retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida. Essa rotina retorna uma status informativa de STATUS_OBJECT_NAME_EXISTS se o chamador solicitou habilitar uma interface do dispositivo que já estava habilitada. Possíveis valores retornados de erro são descritos a seguir.

Código de retorno	Descrição
STATUS_OBJECT_NAME_NOT_FOUND	O chamador tentou desabilitar uma interface do dispositivo que não estava habilitada.

Comentários

IoSetDeviceInterfaceState habilita uma instância de uma interface de dispositivo registrada para uso por aplicativos e outros componentes do sistema. A classe de interface deve ter sido registrada anteriormente com IoRegisterDeviceInterface ou no modo de usuário.

Aplicativos e outros componentes do sistema só podem abrir interfaces habilitadas.

Uma função ou um driver de filtro normalmente chama essa rotina com Habilitar definido como TRUE depois que ele inicia com êxito um dispositivo em resposta a um IRP IRP_MN_START_DEVICE . Esse driver deve desabilitar a instância da interface do dispositivo (ou seja, chamar IoSetDeviceInterfaceState e definir Habilitar como FALSE) quando remover o dispositivo em resposta a um IRP IRP_MN_REMOVE_DEVICE ou a um IRP IRP_MN_SURPRISE_REMOVAL . Se um driver não desabilitar uma interface do dispositivo ao processar esses IRPs de remoção, o driver não deverá tentar fazer isso posteriormente porque o gerenciador PnP desabilitará a interface quando o gerenciador PnP remover o dispositivo.

Se um dispositivo for removido repentinamente (por exemplo, por uma remoção surpresa), mas ainda tiver uma instância de interface de dispositivo válida, ocorrerá um problema se o dispositivo for reanexado. Esse problema ocorre quando o gerenciador PnP enumera o dispositivo recém-anexado e habilita uma instância de interface do dispositivo, que existirá no mesmo caminho do Registro que a instância de interface do dispositivo existente.

Observe que, se o driver chamar IoSetDeviceInterfaceState para desabilitar uma instância de interface do dispositivo em resposta a um IRP IRP_MN_SURPRISE_REMOVAL , o driver não deverá tentar desabilitar a mesma instância de interface do dispositivo em resposta a um IRP IRP_MN_REMOVE_DEVICE .

Se uma chamada para IoSetDeviceInterfaceState expor com êxito uma instância de interface do dispositivo, o sistema notificará todos os componentes registrados para notificação PnP de uma alteração de classe de dispositivo. Da mesma forma, se uma chamada para essa rotina desabilitar uma instância de interface de dispositivo existente, o sistema enviará as notificações apropriadas.

O gerenciador PnP não envia notificação de chegadas de instâncias de interface até que o IRP IRP_MN_START_DEVICE seja concluído, indicando que todos os drivers do dispositivo concluíram suas operações de início. Além disso, o gerenciador PnP falha ao criar solicitações para o dispositivo até que o IRP_MN_START_DEVICE IRP seja concluído.

Os chamadores de IoSetDeviceInterfaceState devem estar em execução em IRQL = PASSIVE_LEVEL no contexto de um thread do sistema.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 2000.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte a seção Comentários)
Regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm), LowerDriverReturn(wdm), PowerIrpDDis(wdm)