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-terminated Unicode 字符串的缓冲区的指针，该字符串表示符号链接名称。 将此指针设置为 NULL 以获取所需的缓冲区大小。

[in, out] pdwSymbolicLinkLengthInChars

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

返回值

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

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

言论

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

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

1. 将 pSymbolicLink 参数设置为 NULL 并调用 RetrieveSymbolicLink。 pdwSymbolicLinkLengthInChars 点的位置接收符号链接名称包含的字符数。
2. 分配足够大的缓冲区，以接收符号链接名称。
3. 再次调用 RetrieveSymbolicLink，并将 pSymbolicLink 参数设置为分配的缓冲区的地址。

例子

下面的代码示例演示如何驱动程序的 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:
...
}

要求

另请参阅

IWDFRemoteInterfaceInitialize

IWDFRemoteInterfaceInitialize：：GetInterfaceGuid