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。 否则， 方法可能会返回以下值：
| 返回代码 | 说明 |
|---|---|
|
pSymbolicLink 指向的缓冲区太小。 在这种情况下，框架将所需的缓冲区大小存储在 pdwSymbolicLinkLengthInChars 指向的位置。 |
此方法可能返回 Winerror.h 包含的其他值之一。
注解
符号链接名称可以包含追加的反斜杠 () 字符，后跟特定于实例的引用字符串。
通常，驱动程序应调用 RetrieveSymbolicLink 两次，如下所示：
- 将 pSymbolicLink 参数设置为 NULL 并调用 RetrieveSymbolicLink。 pdwSymbolicLinkLengthInChars 指向接收符号链接名称包含的字符数的位置。
- 分配一个足以接收符号链接名称的缓冲区。
- 再次调用 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:
...
}
要求
| 要求 | 值 |
|---|---|
| 结束支持 | 在 UMDF 2.0 及更高版本中不可用。 |
| 目标平台 | 桌面 |
| 最低 UMDF 版本 | 1.9 |
| 标头 | wudfddi.h (包括 Wudfddi.h) |
| DLL | WUDFx.dll |