Funzione IoSetDeviceInterfaceState (wdm.h)

Articolo
08/08/2023

La routine IoSetDeviceInterfaceState abilita o disabilita un'istanza di una classe di interfaccia dispositivo registrata in precedenza.

Sintassi

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

Parametri

[in] SymbolicLinkName

Puntatore a una stringa che identifica l'istanza dell'interfaccia del dispositivo abilitata o disabilitata. Questa stringa è stata ottenuta da una chiamata precedente a IoRegisterDeviceInterface o IoGetDeviceInterfaces.

[in] Enable

TRUE indica che l'interfaccia del dispositivo è abilitata. FALSE indica che l'interfaccia del dispositivo è disabilitata.

Valore restituito

IoSetDeviceInterfaceState restituisce STATUS_SUCCESS se la chiamata ha avuto esito positivo. Questa routine restituisce uno stato informativo di STATUS_OBJECT_NAME_EXISTS se il chiamante ha richiesto di abilitare un'interfaccia del dispositivo già abilitata. I valori restituiti di errore possibili sono descritti di seguito.

Codice restituito	Descrizione
STATUS_OBJECT_NAME_NOT_FOUND	Il chiamante ha tentato di disabilitare un'interfaccia del dispositivo non abilitata.

Commenti

IoSetDeviceInterfaceState abilita un'istanza di un'interfaccia dispositivo registrata per l'uso da parte di applicazioni e altri componenti di sistema. La classe di interfaccia deve essere stata registrata in precedenza con IoRegisterDeviceInterface o dalla modalità utente.

Le applicazioni e altri componenti di sistema possono aprire solo le interfacce abilitate.

Una funzione o un driver di filtro chiama in genere questa routine con Enable impostato su TRUE dopo che ha avviato correttamente un dispositivo in risposta a un IRP_MN_START_DEVICE IRP. Tale driver deve disabilitare l'istanza dell'interfaccia del dispositivo, ovvero chiamare IoSetDeviceInterfaceState e impostare Abilita su FALSE, quando rimuove il dispositivo in risposta a un IRP_MN_REMOVE_DEVICE IRP o a un IRP IRP_MN_SURPRISE_REMOVAL . Se un driver non disabilita un'interfaccia del dispositivo quando elabora questi IRP di rimozione, il driver non deve successivamente tentare di eseguire questa operazione perché il gestore PnP disabiliterà l'interfaccia quando il gestore PnP rimuove il dispositivo.

Se un dispositivo viene rimosso improvvisamente (ad esempio, da una rimozione a sorpresa) ma ha ancora un'istanza valida dell'interfaccia del dispositivo, si verificherà un problema se il dispositivo viene ricollegato. Questo problema si verifica quando il gestore PnP enumera il dispositivo appena collegato e abilita un'istanza dell'interfaccia del dispositivo, che sarà presente nello stesso percorso del Registro di sistema dell'istanza dell'interfaccia del dispositivo esistente.

Si noti che se il driver chiama IoSetDeviceInterfaceState per disabilitare un'istanza dell'interfaccia del dispositivo in risposta a un IRP_MN_SURPRISE_REMOVAL IRP, il driver non deve tentare di disabilitare la stessa istanza dell'interfaccia del dispositivo in risposta a un IRP_MN_REMOVE_DEVICE IRP.

Se una chiamata a IoSetDeviceInterfaceState espone correttamente un'istanza dell'interfaccia del dispositivo, il sistema notifica a tutti i componenti registrati per la notifica PnP di una modifica della classe del dispositivo. Analogamente, se una chiamata a questa routine disabilita un'istanza dell'interfaccia del dispositivo esistente, il sistema invia notifiche appropriate.

Il gestore PnP non invia notifiche degli arrivi dell'istanza dell'interfaccia fino al completamento del IRP_MN_START_DEVICE IRP, indicando che tutti i driver per il dispositivo hanno completato le operazioni di avvio. Inoltre, il gestore PnP non riesce a creare richieste per il dispositivo fino al completamento della IRP_MN_START_DEVICE IRP.

I chiamanti di IoSetDeviceInterfaceState 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), IrqlIoPassive1(wdm), LowerDriverReturn(wdm), PowerIrpDDis(wdm)