WdfPdoInitAddDeviceText 函数 (wdfpdo.h)

  • 项目

[仅适用于 KMDF]

对于指定的区域设置， WdfPdoInitAddDeviceText 方法向设备添加设备说明和设备位置。

语法

NTSTATUS WdfPdoInitAddDeviceText(
  [in] PWDFDEVICE_INIT  DeviceInit,
  [in] PCUNICODE_STRING DeviceDescription,
  [in] PCUNICODE_STRING DeviceLocation,
  [in] LCID             LocaleId
);

参数

[in] DeviceInit

指向 WDFDEVICE_INIT 结构的指针。

[in] DeviceDescription

指向 UNICODE_STRING 结构的指针，该结构包含设备说明，为给定的区域设置格式。 驱动程序可以从分页池分配字符串的缓冲区。

[in] DeviceLocation

指向 UNICODE_STRING 结构的指针，该结构包含父设备在总线上找到子设备的位置的说明。 驱动程序可以从分页池分配字符串的缓冲区。

[in] LocaleId

LCID) (区域设置标识符，表示 Unicode 字符串的区域设置。 有关详细信息，请参阅 区域设置标识符。

返回值

如果操作成功，该方法将返回STATUS_SUCCESS。 其他返回值包括：

返回代码 说明
STATUS_INVALID_DEVICE_REQUEST
 驱动程序正在初始化 FDO 而不是 PDO。
STATUS_INSUFFICIENT_RESOURCES
 驱动程序无法分配空间来存储字符串。
 

该方法还可能返回其他 NTSTATUS 值。

注解

框架存储指定的设备文本，并将其传递给 PnP 管理器以响应 IRP_MN_QUERY_DEVICE_TEXT 请求。 你提供的文本应可帮助用户识别设备。 尝试为设备安装其他驱动程序时，PnP 管理器有时会显示文本。

可以多次调用 WdfPdoInitAddDeviceText ，为多个区域设置添加设备文本。 当系统显示文本时，它会选择与当前区域设置匹配的文本（如果可用）。 否则，它将使用默认区域设置的字符串。 驱动程序可以通过调用 WdfPdoInitSetDefaultLocale 来指定驱动程序的默认区域设置。

驱动程序必须先调用 WdfPdoInitAddDeviceText， 然后才能调用 WdfDeviceCreate。 有关调用 WdfDeviceCreate 的详细信息，请参阅 创建框架设备对象。

示例

下面的代码示例提供设备位置和说明的 Unicode 字符串。 说明包括实例编号。 有关使用 WdfPdoInitAddDeviceText 的完整示例，请参阅 KbFiltr 示例驱动程序。

DECLARE_CONST_UNICODE_STRING(deviceLocation,L"Keyboard Filter\0" );
DECLARE_UNICODE_STRING_SIZE(buffer, MAX_ID_LEN);

status = RtlUnicodeStringPrintf(
                                &buffer,
                                L"Keyboard_Filter_%02d",
                                InstanceNo
                                );
if (!NT_SUCCESS(status)) {
    goto Cleanup;
}
status = WdfPdoInitAddDeviceText(
                                 pDeviceInit,
                                 &buffer,
                                 &deviceLocation,
                                 0x409
                                 );
if (!NT_SUCCESS(status)) {
    goto Cleanup;
}

要求

要求 值
目标平台 通用
最低 KMDF 版本 1.0
标头 wdfpdo.h (包括 Wdf.h)
Library Wdf01000.sys (请参阅框架库 Versioning.)
IRQL PASSIVE_LEVEL
DDI 符合性规则 ChildDeviceInitAPI (kmdf) 、DriverCreate (kmdf) 、InitFreeDeviceCallback (kmdf) 、InitFreeDeviceCreate (kmdf) InitFreeNull (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf) ， PdoDeviceInitAPI (kmdf) 、PdoInitFreeDeviceCallback (kmdf) 、PdoInitFreeDeviceCreate (kmdf)

另请参阅

WdfPdoInitSetDefaultLocale