IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink method (wudfddi.h)

2021-10-21

[Warning: UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.]

The RetrieveSymbolicLink method retrieves the symbolic link name that the operating system assigned to a device interface.

Syntax

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

Parameters

[out, optional] pSymbolicLink

A pointer to a buffer that receives a null-terminated Unicode character string that represents the symbolic link name. Set this pointer to NULL to obtain the required buffer size.

[in, out] pdwSymbolicLinkLengthInChars

A pointer to a caller-allocated ___location. On input, this ___location must contain the caller-supplied length of the buffer that pSymbolicLink points to. On output, the ___location receives the length, in characters, of the symbolic link name, including the NULL terminating character.

Return value

RetrieveSymbolicLink returns S_OK if the operation succeeds. Otherwise the method might return the following value:

Return code	Description
E_NOT_SUFFICIENT_BUFFER	The buffer that pSymbolicLink points to is too small. In this case, the framework stores the required buffer size in the ___location that pdwSymbolicLinkLengthInChars points to.

This method might return one of the other values that Winerror.h contains.

Remarks

The symbolic link name can include an appended backslash () character, followed by an instance-specific reference string.

Typically, your driver should call RetrieveSymbolicLink twice, as follows:

Set the pSymbolicLink parameter to NULL and call RetrieveSymbolicLink. The ___location that pdwSymbolicLinkLengthInChars points to receives the number of characters that the symbolic link name contains.
Allocate a buffer that is large enough to receive the symbolic link name.
Call RetrieveSymbolicLink again, and set the pSymbolicLink parameter to the address of the buffer that you allocated.

For more information about the RetrieveSymbolicLink method, see Using Device Interfaces in UMDF-based Drivers.

Examples

The following code example shows how a driver's IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival callback function can determine the length of device interface's symbolic link name, allocate a buffer for the name, and then retrieve the name.

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:
...
}

Requirements

Requirement	Value
End of support	Unavailable in UMDF 2.0 and later.
Target Platform	Desktop
Minimum UMDF version	1.9
Header	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

Share via