Функция WdfDeviceRetrieveDeviceInterfaceString (wdfdevice.h)

Статья
02/07/2025

[Применимо к KMDF и UMDF]

Метод WdfDeviceRetrieveDeviceInterfaceString извлекает имя символьной ссылки, назначенное операционной системе интерфейсу устройства, зарегистрированному драйвером для указанного устройства.

Синтаксис

NTSTATUS WdfDeviceRetrieveDeviceInterfaceString(
  [in]           WDFDEVICE        Device,
  [in]           const GUID       *InterfaceClassGUID,
  [in, optional] PCUNICODE_STRING ReferenceString,
  [in]           WDFSTRING        String
);

Параметры

[in] Device

Дескриптор объекта устройства платформы.

[in] InterfaceClassGUID

Указатель на GUID, определяющий класс интерфейса устройства.

[in, optional] ReferenceString

Указатель на структуру UNICODE_STRING, описывающую эталонную строку для интерфейса устройства. Этот параметр является необязательным и может быть NULL, если драйвер не указал ссылку при вызове WdfDeviceCreateDeviceInterface.

[in] String

Дескриптор объекта строки платформы. Платформа присвоит строке Юникода символьную ссылку строке.

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

WdfDeviceRetrieveDeviceInterfaceString возвращает STATUS_SUCCESS, если операция завершится успешно. В противном случае метод может вернуть одно из следующих значений:

Возвращаемый код	Описание
STATUS_INVALID_DEVICE_REQUEST	WdfDeviceRetrieveDeviceInterfaceString не был вызван в IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Указан недопустимый параметр.
STATUS_INVALID_DEVICE_REQUEST	Указанный объект устройства был инициализирован WdfControlDeviceInitAllocate.
STATUS_OBJECT_NAME_NOT_FOUND	Не удалось найти интерфейс устройства, соответствующий указанному GUID и ссылочной строке.
STATUS_INVALID_DEVICE_STATE	Драйвер, называемый WdfDeviceCreateDeviceInterface, но система еще не назначила символьное имя ссылки интерфейсу устройства.

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

Ошибка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Замечания

Дополнительные сведения об интерфейсах устройств см. в разделе Использование интерфейсов устройств.

Примеры

В следующем примере кода создается строковый объект, а затем извлекается символьное имя символьного канала интерфейса устройства.

NTSTATUS status;
WDFSTRING string;

status = WdfStringCreate(
                         NULL,
                         WDF_NO_OBJECT_ATTRIBUTES,
                         &string
                         );
if (NT_SUCCESS(status)) {
    status = WdfDeviceRetrieveDeviceInterfaceString(
                         Device,
                         &GUID_DEVINTERFACE_DDI_TEST1,
                         NULL,
                         string
                         );
    if (!NT_SUCCESS(status)) {
        return status;
    }
}

Требования

Требование	Ценность
целевая платформа	Всеобщий
минимальная версия KMDF	1.0
минимальная версия UMDF	2.0
заголовка	wdfdevice.h (include Wdf.h)
библиотеки	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
правил соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

См. также

UNICODE_STRING

WdfControlDeviceInitAllocate

WdfDeviceCreateDeviceInterface

WdfStringCreate

Поделиться через