IRP_MN_QUERY_DEVICE_TEXT

The PnP manager uses this IRP to get a device's description or location information.

Bus drivers must handle this request for their child devices if the bus supports this information. Function and filter drivers do not handle this IRP.

Value

0x0C

Major Code

IRP_MJ_PNP

When Sent

The PnP manager sends two of these IRPs when a device is enumerated: one to query the device description and one to query the location information.

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

Input Parameters

The Parameters.QueryDeviceText.DeviceTextType member of the IO_STACK_LOCATION structure is a DEVICE_TEXT_TYPE value specifying which string is requested. Possible values for DEVICE_TEXT_TYPE include DeviceTextDescription and DeviceTextLocationInformation.

Parameters.QueryDeviceText.LocaleId is an LCID specifying the locale for the requested text.

Output Parameters

Returned in the I/O status block.

I/O Status Block

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

On success, a bus driver sets Irp->IoStatus.Information to a pointer to a driver-allocated block of memory containing a WCHAR buffer with the requested information. On an error, the bus driver sets Irp->IoStatus.Information to zero.

Operation

Bus drivers are strongly encouraged to return device descriptions for their child devices. This string is displayed in the Found New Hardware pop-up window if no INF match is found for the device.

Bus drivers are also encouraged to return LocationInformation for their child devices, but this information is optional. The format of this string depends on the bus. The Device manager displays this string in the general properties tab for the device. Vendors should choose a string that conveys useful information to users and support personnel. For example, for PCI, the string contains the bus, device, and function. For PC Card, the string contains the slot.

If a bus driver returns information in response to this IRP, it allocates a NULL-terminated Unicode string from paged memory. The PnP manager frees the string when it is no longer needed.

If a device does not provide description or location information, the device's parent bus driver completes the IRP (IoCompleteRequest) without modifying Irp->IoStatus.Status or Irp->IoStatus.Information.

Function and filter drivers do not handle this IRP; they pass it to the next lower driver with no changes to Irp->IoStatus.

Drivers for buses that support different text strings for different locales should be able to handle a request for a language that is not explicitly supported by the device. In such a situation, the bus driver should return the closest match for the locale or should fallback and return some appropriate supported locale string.

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