共用方式為

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。 否則方法可能會傳回下列值：

傳回碼 描述
E_NOT_SUFFICIENT_BUFFER
 pSymbolicLink 指向的緩衝區太小。 在此情況下，架構會將所需的緩衝區大小儲存在 pdwSymbolicLinkLengthInChars 指向的位置。
 

這個方法可能會傳回 Winerror.h 所包含的其他其中一個值。

言論

符號連結名稱可以包含附加的反斜杠 （） 字元，後面接著實例特定的參考字串。

一般而言，您的驅動程序應該呼叫 RetrieveSymbolicLink 兩次，如下所示：

  1. 將 pSymbolicLink 參數設定為 NULL，並呼叫 RetrieveSymbolicLink。 pdwSymbolicLinkLengthInChars 點的位置，接收符號連結名稱包含的字元數。
  2. 配置足以接收符號連結名稱的緩衝區。
  3. 再次呼叫 RetrieveSymbolicLink，並將 pSymbolicLink 參數設定為您配置的緩衝區位址。
如需 RetrieveSymbolicLink 方法的詳細資訊，請參閱 在 UMDF 型驅動程式中使用裝置介面。

例子

下列程式代碼範例示範驅動程式 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

另請參閱

IWDFRemoteInterfaceInitialize

IWDFRemoteInterfaceInitialize：：GetInterfaceGuid