IRP_MN_QUERY_PNP_DEVICE_STATE

Function, filter, and bus drivers can handle this request.

Major Code

IRP_MJ_PNP

When Sent

The PnP manager sends this IRP after the drivers for a device return success from the IRP_MN_START_DEVICE request sent when a device is first started. This IRP is not sent on a start after a stop for resource rebalancing. The PnP manager also sends this IRP when a driver for the device calls IoInvalidateDeviceState.

The PnP manager sends this IRP at IRQL PASSIVE_LEVEL in the context of an arbitrary thread.

Input Parameters

None

Output Parameters

Returned in I/O status block.

I/O Status Block

A driver sets Irp->IoStatus.Status to STATUS_SUCCESS or to an appropriate error status such as STATUS_UNSUCCESSFUL.

On success, a driver sets Irp->IoStatus.Information to a PNP_DEVICE_STATE bitmask.

The PNP_DEVICE_STATE type is a bitmask that describes the PnP state of a device. A driver returns a value of this type in response to an IRP_MN_QUERY_PNP_DEVICE_STATE request.

typedef ULONG PNP_DEVICE_STATE, *PPNP_DEVICE_STATE;

The flag bits in a PNP_DEVICE_STATE value are defined as follows.

Flag bit Description
PNP_DEVICE_DISABLED

The device is physically present but is disabled in hardware.

PNP_DEVICE_DONT_DISPLAY_IN_UI

Do not display the device in the user interface. Set for a device that is physically present but not usable in the current configuration, such as a game port on a laptop that is not usable when the laptop is undocked. (Also see the NoDisplayInUI flag in the DEVICE_CAPABILITIES structure.)

PNP_DEVICE_FAILED

The device is present but not functioning properly.

When both this flag and PNP_DEVICE_RESOURCE_REQUIREMENTS_CHANGED are set, the device must be stopped before the PnP manager assigns new hardware resources (nonstop rebalance is not supported for the device).

PNP_DEVICE_NOT_DISABLEABLE

The device is required when the computer starts. Such a device must not be disabled.

A driver sets this bit for a device that is required for proper system operation. For example, if a driver receives notification that a device is in the paging path (IRP_MN_DEVICE_USAGE_NOTIFICATION for DeviceUsageTypePaging), the driver calls IoInvalidateDeviceState and sets this flag in the resulting IRP_MN_QUERY_PNP_DEVICE_STATE request.

If this bit is set for a device, the PnP manager propagates this setting to the device's parent device, its parent's parent device, and so forth.

If this bit is set for a root-enumerated device, the device cannot be disabled or uninstalled.

PNP_DEVICE_REMOVED

The device has been physically removed.

PNP_DEVICE_RESOURCE_REQUIREMENTS_CHANGED

The resource requirements for the device have changed.

Typically, a bus driver sets this flag when it has determined that it must expand its resource requirements in order to enumerate a new child device.

PNP_DEVICE_DISCONNECTED

The device driver is loaded, but this driver has detected that the device is no longer connected to the computer. Typically, this flag is used for function drivers that communicate with wireless devices. For example, the flag is set when the device moves out of range, and is cleared after the device moves back into range and re-connects.

A bus driver does not typically set this flag. The bus driver should instead stop enumerating the child device if the device is no longer connected. This flag is used only if the function driver manages the connection.

The sole purpose of this flag is to let clients know whether the device is connected. Setting the flag does not affect whether the driver is loaded.

The PnP manager queries a device's PNP_DEVICE_STATE right after starting the device by sending an IRP_MN_QUERY_PNP_DEVICE_STATE request to the device stack. In response to this IRP, the drivers for the device set the appropriate flags in PNP_DEVICE_STATE.

If any of the state characteristics change after the initial query, a driver notifies the PnP manager by calling IoInvalidateDeviceState. In response to a call to IoInvalidateDeviceState, the PnP manager queries the device's PNP_DEVICE_STATE again.

If a device is marked PNP_DEVICE_NOT_DISABLEABLE, the debugger displays a DNUF_NOT_DISABLEABLE user flag for the devnode. The debugger also displays a DisableableDepends value that counts the number of reasons why the device cannot be disabled. This value is the sum of X+Y, where X is one if the device cannot be disabled and Y is the count of the device's child devices that cannot be disabled.

If a function or filter driver does not handle this IRP, it calls IoSkipCurrentIrpStackLocation, does not set an IoCompletion routine, and passes the IRP down to the next driver. Such a driver must not modify Irp->IoStatus and must not complete the IRP.

If a bus driver does not handle this IRP, it leaves Irp->IoStatus.Status as is and completes the IRP.

Operation

This IRP is handled first by the driver at the top of the device stack and then by each next lower driver in the stack.

A driver handles this IRP if it has information about the PnP state of a device. A driver can set or clear the flags in the PNP_DEVICE_STATE bitmask. If another driver has set a PNP_DEVICE_STATE in Irp->IoStatus.Information, a driver must take care to modify the flags in that bitmask rather than overwrite the whole structure.

See Plug and Play for the general rules for handling Plug and Play minor IRPs.

Sending This IRP

Reserved for system use. Drivers must not send this IRP.

Requirements

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

See also

IoInvalidateDeviceState

PNP_DEVICE_STATE


Send comments about this topic to Microsoft