通过

IWDFDevice2：：CreateSymbolicLinkWithReferenceString 方法 (wudfddi.h)

  • 项目

[警告： UMDF 2 是最新版本的 UMDF，取代了 UMDF 1。 所有新的 UMDF 驱动程序都应使用 UMDF 2 编写。 未向 UMDF 1 添加新功能，并且较新版本的 Windows 10 上对 UMDF 1 的支持有限。 通用 Windows 驱动程序必须使用 UMDF 2。 有关详细信息，请参阅使用 UMDF 入门。]

CreateSymbolicLinkWithReferenceString 方法为设备创建符号链接名称和引用字符串（可选）

语法

HRESULT CreateSymbolicLinkWithReferenceString(
  [in]           PCWSTR pSymbolicLink,
  [in, optional] PCWSTR pReferenceString
);

参数

[in] pSymbolicLink

指向以 NULL 结尾的字符串的指针，该字符串将成为设备的用户可见名称。 符号链接名称必须位于全局 DosDevices 命名空间中。

[in, optional] pReferenceString

指向以 NULL 结尾的字符串的指针，当应用程序使用 pSymbolicLink 参数指定的符号名称时，Windows 会将该字符串追加到设备名称中。 有关更多信息，请参见下面的“备注”部分。 此参数是可选的，可以为 NULL。

返回值

如果操作成功，CreateSymbolicLinkWithReferenceString 将返回S_OK。 否则，该方法可能会返回以下值之一：

返回代码 说明
E_INVALIDARG
 调用方为输入参数指定了无效值。
E_OUTOFMEMORY
 内存分配失败。
 

此方法可能会返回 Winerror.h 包含的其他值之一。

注解

CreateSymbolicLinkWithReferenceString 为 IWDFDevice2 接口表示的设备创建符号链接名称和引用字符串（可选）。 驱动程序调用 CreateSymbolicLinkWithReferenceString 后，应用程序可以使用符号链接名称访问设备。

假设设备的名称为“\Device\MyDevice”。 可以通过为 pSymbolicLink 参数指定“L”DeviceUserName“，为设备创建”DeviceUserName“的符号链接名称。 如果为 pReferenceString 参数指定“L”Instance3“，则会创建指向 \Device\MyDevice\Instance3 的符号链接。 如果应用程序使用符号链接名称打开设备，则 I/O 管理器将打开 \Device\MyDevice，并创建包含 \Instance3 字符串作为文件名的 WDM 文件对象。 基于 UMDF 的驱动程序接收框架创建的文件对象，该对象还包含 \Instance3 字符串作为文件名 (请参阅 IWDFFile：：RetrieveFileName) 。

通常，基于框架的驱动程序提供应用程序可用于访问其 设备的设备接口 ，而不是提供符号链接。

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

如果不需要将引用字符串添加到设备的符号链接名称，驱动程序可以调用 IWDFDevice：：CreateSymbolicLink 而不是 CreateSymbolicLinkWithReferenceString。

示例

以下行定义全局 DosDevices 命名空间中的符号链接名称前缀。

#define SYMBOLIC_LINK_NAME_PREFIX   L"\\DosDevices\\Global\\"

下面的代码示例创建符号名称字符串，获取 IWDFDevice2 接口，然后调用 CreateSymbolicLinkWithReferenceString。


    IWDFDevice2 *pDevice2 = NULL;
    HRESULT hr;

    //
    // Create symbolic link name string.
    //
    hr = StringCchPrintf(portFullName,
                         portFullNameLength,
                         L"%ws%ws",
                         SYMBOLIC_LINK_NAME_PREFIX,
                         portName);
    if (FAILED(hr))
    {
        goto Exit;
    }

    //
    // Get a pointer to the IWDFDevice2 interface.
    //
    hr = pIWDFDevice->QueryInterface(__uuidof(IWDFDevice2),
                                     (void**) &pDevice2);
    if (SUCCEEDED(hr)) 
    {
    hr = pDevice2->CreateSymbolicLinkWithReferenceString(portFullName,
                                                         portCountString);
    if (FAILED(hr))
        {
            goto Exit;
        }
        SAFE_RELEASE(pDevice2);
    }

要求

要求 值
结束支持 在 UMDF 2.0 及更高版本中不可用。
目标平台 桌面
最低 UMDF 版本 1.9
标头 wudfddi.h (包括 Wudfddi.h)
DLL WUDFx.dll

另请参阅

IWDFDevice2

IWDFDevice：：CreateSymbolicLink