IWDFRemoteInterfaceInitialize：：RetrieveSymbolicLink 方法 (wudfddi.h)

[警告： UMDF 2 是最新版的 UMDF，並取代 UMDF 1。 所有新的 UMDF 驅動程式都應該使用 UMDF 2 來撰寫。 未將新功能新增至 UMDF 1，且較新版本的 #D910F8CB586AA47DCA57A826A372A2F12 上不支援 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。 否則，方法可能會傳回下列值：

這個方法可能會傳回 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