通过

IWDFRemoteInterfaceInitialize：：RetrieveSymbolicLink 方法 (wudfddi.h)

  • 项目

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

RetrieveSymbolicLink 方法检索操作系统分配给设备接口的符号链接名称。

语法

HRESULT RetrieveSymbolicLink(
  [out, optional] PWSTR pSymbolicLink,
  [in, out]       DWORD *pdwSymbolicLinkLengthInChars
);

参数

[out, optional] pSymbolicLink

指向缓冲区的指针，该缓冲区接收表示符号链接名称的 以 null 结尾的 Unicode 字符串。 将此指针设置为 NULL 以获取所需的缓冲区大小。

[in, out] pdwSymbolicLinkLengthInChars

指向调用方分配的位置的指针。 输入时，此位置必须包含 pSymbolicLink 指向的缓冲区的调用方提供的长度。 在输出时，位置接收符号链接名称的长度（以字符为单位），包括 NULL 终止字符。

返回值

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

返回代码 说明
E_NOT_SUFFICIENT_BUFFER
 pSymbolicLink 指向的缓冲区太小。 在这种情况下，框架将所需的缓冲区大小存储在 pdwSymbolicLinkLengthInChars 指向的位置。
 

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

注解

符号链接名称可以包含追加的反斜杠 () 字符，后跟特定于实例的引用字符串。

通常，驱动程序应调用 RetrieveSymbolicLink 两次，如下所示：

  1. 将 pSymbolicLink 参数设置为 NULL 并调用 RetrieveSymbolicLink。 pdwSymbolicLinkLengthInChars 指向接收符号链接名称包含的字符数的位置。
  2. 分配一个足以接收符号链接名称的缓冲区。
  3. 再次调用 RetrieveSymbolicLink ，并将 pSymbolicLink 参数设置为已分配的缓冲区的地址。
有关 RetrieveSymbolicLink 方法的详细信息，请参阅 在基于 UMDF 的驱动程序中使用设备接口。

示例

下面的代码示例演示驱动程序的 IPnpCallbackRemoteInterfaceNotification：：OnRemoteInterfaceArrival 回调函数如何确定设备接口的符号链接名称的长度、为名称分配缓冲区，然后检索名称。

void 
STDMETHODCALLTYPE
CMyDevice::OnRemoteInterfaceArrival(
    __in IWDFRemoteInterfaceInitialize  *FxRemoteInterfaceInit
    )
{
    HRESULT hr;
    INT BufferSize;
    hr= FxRemoteInterfaceInit->RetrieveSymbolicLink(NULL,
                                                    &BufferSize);
    if (FAILED(hr)) goto Error;
    hr = FxDriver->CreateWdfMemory(BufferSize, 
                                   NULL, 
                                   FxRemoteInterface, 
                                   &FxSymLinkBuffer);
    if (FAILED(hr)) goto Error;
    hr= FxRemoteInterfaceInit->RetrieveSymbolicLink(FxSymLinkBuffer->GetDataBuffer(NULL),
                                                    &BufferSize);
    if (FAILED(hr)) goto Error;
...
Error:
...
}

要求

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

另请参阅

IWDFRemoteInterfaceInitialize

IWDFRemoteInterfaceInitialize：：GetInterfaceGuid