IoSetDeviceInterfaceState

The IoSetDeviceInterfaceState routine enables or disables an instance of a previously registered device interface class.

NTSTATUS 
  IoSetDeviceInterfaceState(
    IN PUNICODE_STRING  SymbolicLinkName,
    IN BOOLEAN  Enable
    );

Parameters

SymbolicLinkName

Pointer to a string identifying the device interface instance being enabled or disabled. This string was obtained from a previous call to IoRegisterDeviceInterface or IoGetDeviceInterfaces.

Enable

TRUE indicates that the device interface is being enabled. FALSE indicates that the device interface is being disabled.

Return Value

IoSetDeviceInterfaceState returns STATUS_SUCCESS if the call was successful. This routine returns an informational status of STATUS_OBJECT_NAME_EXISTS if the caller requested to enable a device interface that was already enabled. Possible error return values are described following.

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Comments

IoSetDeviceInterfaceState enables an instance of a registered device interface for use by applications and other system components. The interface class must have been previously registered with IoRegisterDeviceInterface or from user mode.

Applications and other system components can open only interfaces that are enabled.

A function or filter driver typically calls this routine with Enable set to TRUE after it successfully starts a device in response to an IRP_MN_START_DEVICE. Such a driver should disable the device interface instance (Enable equals FALSE) when it removes the device in response to an IRP_MN_REMOVE_DEVICE.

If a call to this routine successfully exposes a device interface instance, the system notifies any components that registered for PnP notification of a device class change. Similarly, if a call to this routine disables an existing device interface instance, the system sends appropriate notifications.

The PnP Manager does not send notification of interface instance arrivals until the IRP_MN_START_DEVICE IRP completes, indicating that all the drivers for the device have completed their start operations. In addition, the PnP Manager fails create requests for the device until the IRP_MN_START_DEVICE IRP completes.

Callers of IoSetDeviceInterfaceState must be running at IRQL = PASSIVE_LEVEL in the context of a system thread.

See Also

IoGetDeviceInterfaces, IoRegisterDeviceInterface, IoRegisterPlugPlayNotification