IRP_MN_QUERY_DEVICE_TEXT

IRP_MN_QUERY_DEVICE_TEXT

The PnP manager uses this IRP to get a device’s description or location information.
PnP 管理器使用此 IRP 获取设备的描述或位置信息。

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.
如果总线支持此信息, 则总线驱动程序必须处理其子设备的此请求。函数和过滤驱动程序不处理此 IRP。

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.
当枚举设备时, PnP manager 会发送两个 IRPs: 一个用于查询设备描述, 一个用于查询位置信息。

The PnP manager sends this IRP at IRQL PASSIVE_LEVEL in an arbitrary thread context.
PnP 管理器在任意线程上下文中 IRQL PASSIVE_LEVEL 发送此 IRP。

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.
IO_STACK_LOCATION 结构的Parameters.QueryDeviceText.DeviceTextType成员是一个DEVICE_TEXT_TYPE值, 指定请求哪个字符串。DEVICE_TEXT_TYPE的可能值包括DeviceTextDescription和DeviceTextLocationInformation.

Parameters.QueryDeviceText.LocaleId is an LCID specifying the locale for the requested text.
Parameters.QueryDeviceText.LocaleId是一个 LCID, 用于指定所请求文本的区域设置。

Output Parameters

Returned in the I/O status block.
在 i/o 状态块中返回。

I/O Status Block

A driver sets Irp->IoStatus.Status to STATUS_SUCCESS or to an appropriate error status.
驱动程序将Irp -> IoStatus 的状态设置为 STATUS_SUCCESS 或相应的错误状态。

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.
成功时, 总线驱动程序将Irp -> IoStatus 的信息设置为指向驱动程序分配的内存块的指针, 其中包含带有所请求信息的 WCHAR 缓冲区。在出错时, 总线驱动程序将Irp -> IoStatus 的信息设置为零。

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.
强烈鼓励总线驱动程序返回其子设备的设备说明。如果未找到设备的 INF 匹配, 则此字符串显示在 “找到新硬件” 弹出窗口中。

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.
还鼓励总线驱动程序为其子设备返回LocationInformation , 但此信息是可选的。此字符串的格式取决于总线。设备管理器在设备的 “常规属性” 选项卡中显示此字符串。供应商应选择一个字符串, 向用户和支持人员传递有用的信息。例如, 对于 PCI, 字符串包含总线、设备和函数。对于 PC 卡, 字符串包含插槽。

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.
如果总线驱动程序返回信息以响应此 IRP, 它将从分页内存中分配一个以 NULL 结尾的 Unicode 字符串。当该字符串不再需要时, PnP manager 会释放它。

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.
如果设备不提供说明或位置信息, 设备的父总线驱动程序将完成 irp (IoCompleteRequest), 而不修改irp -> IoStatus. 状态或irp -> IoStatus. 信息.

Function and filter drivers do not handle this IRP; they pass it to the next lower driver with no changes to Irp->IoStatus.
函数和过滤驱动程序不处理此 IRP;他们将其传递给下一个较低的驱动程序, 不更改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.
有关处理即插即用小 IRPs的一般规则, 请参阅即插即用.

Sending This IRP

Reserved for system use. Drivers must not send this IRP.
保留供系统使用。驱动程序不能发送此 IRP。

Requirements

Header

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