共用方式為

IWDFDevice2：：CreateSymbolicLinkWithReferenceString 方法 （wudfddi.h）

  • 發行項

[警告： UMDF 2 是最新版本的 UMDF，並取代 UMDF 1。 所有新的UMDF驅動程式都應該使用UMDF 2撰寫。 未將新功能新增至 UMDF 1，而且較新版本的 Windows 10 上對 UMDF 1 的支援有限。 通用 Windows 驅動程式必須使用 UMDF 2。 如需詳細資訊，請參閱 開始使用 UMDF。]

CreateSymbolicLinkWithReferenceString 方法會建立符號連結名稱，並選擇性地建立裝置的參考字元串

語法

HRESULT CreateSymbolicLinkWithReferenceString(
  [in]           PCWSTR pSymbolicLink,
  [in, optional] PCWSTR pReferenceString
);

參數

[in] pSymbolicLink

NULL終止字元字串的指標，成為裝置的使用者可見名稱。 符號連結名稱必須位於全域 DosDevices 命名空間中。

[in, optional] pReferenceString

當應用程式使用 pSymbolicLink 參數所指定之符號 名稱時，Windows 附加至裝置名稱的 NULL終止字元字串指標。 如需詳細資訊，請參閱下列一節。 這個參數是選擇性的，而且可以 NULL。

傳回值

CreateSymbolicLinkWithReferenceString 如果作業成功，就會傳回S_OK。 否則，方法可能會傳回下列其中一個值：

傳回碼 描述
E_INVALIDARG
 呼叫端為輸入參數指定了無效的值。
E_OUTOFMEMORY
 記憶體配置失敗。
 

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

言論

CreateSymbolicLinkWithReferenceString 會為 IWDFDevice2 介面所代表的裝置建立符號連結名稱，以及選擇性的參考字串。 在驅動程式呼叫 CreateSymbolicLinkWithReferenceString之後，應用程式可以使用符號連結名稱來存取裝置。

假設裝置的名稱是 “\Device\MyDevice”。 您可以為裝置建立 「DeviceUserName」 的符號連結名稱，方法是為 pSymbolicLink 參數指定 “L”DeviceUserName“。 如果您為 pReferenceString 參數指定 “L”Instance3“，您要建立 \Device\MyDevice\Instance3 的符號連結。 如果應用程式使用符號連結名稱開啟裝置，I/O 管理員會開啟 \Device\MyDevice，並建立包含 \Instance3 字符串作為檔名的 WDM 檔案物件。 以UMDF為基礎的驅動程式會收到架構建立的檔案物件，其中也包含 \Instance3 字串作為檔名（請參閱 IWDFFile：：RetrieveFileName）。

一般而言，架構型驅動程式不會提供符號連結，而是提供 裝置介面， 應用程式可用來存取其裝置。

如果裝置意外移除（意外移除），架構會移除裝置的符號連結。 然後，驅動程式可以使用裝置新實例的符號連結名稱。

如果您不需要將參考字串新增至裝置的符號連結名稱，驅動程式可以呼叫 IWDFDevice：：CreateSymbolicLink，而不是 CreateSymbolicLinkWithReferenceString。

例子

下行會在全域 DosDevices 命名空間中定義符號連結名稱前置詞。

#define SYMBOLIC_LINK_NAME_PREFIX   L"\\DosDevices\\Global\\"

下列程式代碼範例會建立符號名稱字串、取得 IWDFDevice2 介面，然後呼叫 CreateSymbolicLinkWithReferenceString。


    IWDFDevice2 *pDevice2 = NULL;
    HRESULT hr;

    //
    // Create symbolic link name string.
    //
    hr = StringCchPrintf(portFullName,
                         portFullNameLength,
                         L"%ws%ws",
                         SYMBOLIC_LINK_NAME_PREFIX,
                         portName);
    if (FAILED(hr))
    {
        goto Exit;
    }

    //
    // Get a pointer to the IWDFDevice2 interface.
    //
    hr = pIWDFDevice->QueryInterface(__uuidof(IWDFDevice2),
                                     (void**) &pDevice2);
    if (SUCCEEDED(hr)) 
    {
    hr = pDevice2->CreateSymbolicLinkWithReferenceString(portFullName,
                                                         portCountString);
    if (FAILED(hr))
        {
            goto Exit;
        }
        SAFE_RELEASE(pDevice2);
    }

要求

要求 價值
終止支援 UMDF 2.0 和更新版本中無法使用。
目標平臺 桌面
最低 UMDF 版本 1.9
標頭 wudfddi.h （包括 Wudfddi.h）
DLL WUDFx.dll

另請參閱

IWDFDevice2

IWDFDevice：：CreateSymbolicLink