WdfPdoInitAddDeviceText function (wdfpdo.h)

Article
04/18/2022

[Applies to KMDF only]

The WdfPdoInitAddDeviceText method adds a device description and device location to a device, for a specified locale.

Syntax

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

Parameters

[in] DeviceInit

A pointer to a WDFDEVICE_INIT structure.

[in] DeviceDescription

A pointer to a UNICODE_STRING structure that contains a device description, formatted for the given locale. The driver can allocate the string's buffer from paged pool.

[in] DeviceLocation

A pointer to a UNICODE_STRING structure that contains a description of the location on the bus where the parent device found the child. The driver can allocate the string's buffer from paged pool.

[in] LocaleId

A locale identifier (LCID) that represents the locale of the Unicode strings. For more information, see Locale Identifiers.

Return value

If the operation succeeds, the method returns STATUS_SUCCESS. Additional return values include:

Return code	Description
STATUS_INVALID_DEVICE_REQUEST	The driver is initializing an FDO instead of a PDO.
STATUS_INSUFFICIENT_RESOURCES	The driver could not allocate space to store the strings.

The method might also return other NTSTATUS values.

Remarks

The framework stores the specified device text and passes it to the PnP manager in response to an IRP_MN_QUERY_DEVICE_TEXT request. The text that you supply should help the user to identify the device. The PnP manager sometimes displays the text while attempting to install additional drivers for the device.

You can call WdfPdoInitAddDeviceText multiple times, adding device text for multiple locales. When the system displays the text, it chooses the text that matches the current locale, if available. Otherwise, it will use the string for the default locale. The driver can specify the driver's default locale by calling WdfPdoInitSetDefaultLocale.

The driver must call WdfPdoInitAddDeviceText before calling WdfDeviceCreate. For more information about calling WdfDeviceCreate, see Creating a Framework Device Object.

Examples

The following code example provides Unicode strings for a device's location and description. The description includes an instance number. For a complete example that uses WdfPdoInitAddDeviceText, see the KbFiltr sample driver.

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;
}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Header	wdfpdo.h (include Wdf.h)
Library	Wdf01000.sys (see Framework Library Versioning.)
IRQL	PASSIVE_LEVEL
DDI compliance rules	ChildDeviceInitAPI(kmdf), DriverCreate(kmdf), InitFreeDeviceCallback(kmdf), InitFreeDeviceCreate(kmdf), InitFreeNull(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), PdoDeviceInitAPI(kmdf), PdoInitFreeDeviceCallback(kmdf), PdoInitFreeDeviceCreate(kmdf)