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

代表 Unicode 字串地區設定的地區設定標識子 (LCID) 。 如需詳細資訊，請參閱 地區設定標識符。

傳回值

如果作業成功，方法會傳回STATUS_SUCCESS。 其他傳回值包括：

傳回碼	Description
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;
}

規格需求

需求	值
目標平台	Universal
最低 KMDF 版本	1.0
標頭	wdfpdo.h (包含 Wdf.h)
程式庫	Wdf01000.sys (請參閱 Framework Library 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