nf-wudfddi-iwdfremoteinterfaceinitialize-retrievesymboliclink.md

UID	title	description	old-location	tech.root	ms.date	keywords	ms.keywords	req.header	req.include-header	req.target-type	req.target-min-winverclnt	req.target-min-winversvr	req.kmdf-ver	req.umdf-ver	req.ddi-compliance	req.unicode-ansi	req.idl	req.max-support	req.namespace	req.assembly	req.type-library	req.lib	req.dll	req.irql	targetos	req.typenames	f1_keywords	topic_type	api_type	api_location	api_name
NF:wudfddi.IWDFRemoteInterfaceInitialize.RetrieveSymbolicLink	IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink (wudfddi.h)	The RetrieveSymbolicLink method retrieves the symbolic link name that the operating system assigned to a device interface.	wdf\iwdfremoteinterfaceinitialize_retrievesymboliclink.htm	wdf	02/26/2018	IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink	IWDFRemoteInterfaceInitialize interface,RetrieveSymbolicLink method, IWDFRemoteInterfaceInitialize.RetrieveSymbolicLink, IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink, RetrieveSymbolicLink, RetrieveSymbolicLink method, RetrieveSymbolicLink method,IWDFRemoteInterfaceInitialize interface, UMDFIoTargetObjectRef_e76cdd61-351a-43f9-93a6-6991159e3d53.xml, umdf.iwdfremoteinterfaceinitialize_retrievesymboliclink, wdf.iwdfremoteinterfaceinitialize_retrievesymboliclink, wudfddi/IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink	wudfddi.h	Wudfddi.h	Desktop				1.9				Unavailable in UMDF 2.0 and later.					WUDFx.dll		Windows		IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink wudfddi/IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink	APIRef kbSyntax	COM	WUDFx.dll	IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink

IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink

-description

[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.

-parameters

-param pSymbolicLink [out, optional]

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.

-param pdwSymbolicLinkLengthInChars [in, out]

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.

-returns

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:

1. 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.
2. Allocate a buffer that is large enough to receive the symbolic link name.
3. 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:
...
}

-see-also

IWDFRemoteInterfaceInitialize

IWDFRemoteInterfaceInitialize::GetInterfaceGuid