WdfDeviceCreateSymbolicLink 函数 (wdfdevice.h)

[适用于 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 值

如果驱动程序提供无效的对象句柄,则会发生 bug 检查。

注解

如果驱动程序为设备创建符号链接,应用程序可以使用符号链接名称来访问设备。 通常,基于框架的驱动程序提供应用程序可用于访问其 设备的设备接口 ,而不是提供符号链接。

如果意外删除设备 (意外删除) ,框架将删除指向设备的符号链接。 然后,驱动程序可以将符号链接名称用于设备的新实例。

示例

以下来自 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)
Library Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
DDI 符合性规则 DriverCreate (kmdf) KmdfIrql (kmdf) KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)

另请参阅

UNICODE_STRING