Функция WdfPdoInitAddDeviceText (wdfpdo.h)

Статья
08/08/2023

[Относится только к 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), представляющий языковой стандарт строк Юникода. Дополнительные сведения см. в разделе Идентификаторы языкового стандарта.

Возвращаемое значение

Если операция выполнена успешно, метод возвращает STATUS_SUCCESS. К дополнительным возвращаемым значениям относятся:

Код возврата	Описание
STATUS_INVALID_DEVICE_REQUEST	Драйвер инициализирует FDO вместо PDO.
STATUS_INSUFFICIENT_RESOURCES	Драйверу не удалось выделить место для хранения строк.

Метод также может возвращать другие значения NTSTATUS.

Платформа сохраняет указанный текст устройства и передает его диспетчеру PnP в ответ на запрос IRP_MN_QUERY_DEVICE_TEXT . Текст, который вы указываете, должен помочь пользователю идентифицировать устройство. Диспетчер PnP иногда отображает текст при попытке установить дополнительные драйверы для устройства.

Вы можете вызывать WdfPdoInitAddDeviceText несколько раз, добавляя текст устройства для нескольких языковых стандартов. Когда система отображает текст, она выбирает текст, соответствующий текущему языковому стандарту, если он доступен. В противном случае он будет использовать строку для языкового стандарта по умолчанию. Драйвер может указать языковой стандарт драйвера по умолчанию, вызвав WdfPdoInitSetDefaultLocale.

Драйвер должен вызвать WdfPdoInitAddDeviceText перед вызовом WdfDeviceCreate. Дополнительные сведения о вызове WdfDeviceCreate см. в разделе Создание объекта устройства платформы.

Примеры

В следующем примере кода приведены строки Юникода для расположения и описания устройства. Описание содержит номер экземпляра. Полный пример использования 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)
Библиотека	Wdf01000.sys (см. раздел Управление версиями библиотеки Платформы).
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