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

Статья
08/08/2023

[Относится к 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 (включая Wdf.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

См. также раздел

UNICODE_STRING