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

Статья
02/07/2025

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

Метод WdfDeviceCreateSymbolicLink создает символьную ссылку на указанное устройство.

Синтаксис

NTSTATUS WdfDeviceCreateSymbolicLink(
  [in] WDFDEVICE        Device,
  [in] PCUNICODE_STRING SymbolicLinkName
);

Параметры

[in] Device

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

[in] SymbolicLinkName

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

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

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

Возвращаемый код	Описание
STATUS_INSUFFICIENT_RESOURCES	Система не может выделить место для хранения имени устройства.

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

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

Замечания

Если драйвер создает символьную ссылку для устройства, приложения могут использовать имя символьной ссылки для доступа к устройству. Как правило, вместо предоставления символьных ссылок драйверы на основе платформы предоставляют интерфейсы устройств, которые приложения могут использовать для доступа к своим устройствам.

Если устройство удалено неожиданно (неожиданно удалено), платформа удаляет символьную ссылку на устройство. Затем драйвер может использовать символьное имя ссылки для нового экземпляра устройства.

Примеры

В следующем примере кода из драйвера KMDF создается MS-DOS имя устройства, которое приложение может использовать для доступа к устройству.

#define DOS_DEVICE_NAME  L"\\DosDevices\\MyDevice"
DECLARE_CONST_UNICODE_STRING(dosDeviceName, DOS_DEVICE_NAME);
NTSTATUS  status;

status = WdfDeviceCreateSymbolicLink(
                                     controlDevice,
                                     &dosDeviceName
                                     );
if (!NT_SUCCESS(status)) {
    goto Error;
}

Драйвер UMDF должен предоставить символьное имя ссылки в глобальном DosDevices пространства имен, как показано в следующем примере кода.

#define DOS_DEVICE_NAME  L"\\DosDevices\\Global\\MyDevice"
DECLARE_CONST_UNICODE_STRING(dosDeviceName, DOS_DEVICE_NAME);
NTSTATUS  status;

status = WdfDeviceCreateSymbolicLink(
                                     controlDevice,
                                     &dosDeviceName
                                     );
if (!NT_SUCCESS(status)) {
    goto Error;
}

Сведения о глобальных и локальных \DosDevices пространствах имен см. в локальных и глобальных MS-DOS имен устройств.

Требования

Требование	Ценность
целевая платформа	Всеобщий
минимальная версия 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

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