共用方式為

IWDFDevice2：：CreateSymbolicLinkWithReferenceString 方法 (wudfddi.h)

  • 發行項

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

傳回碼 Description
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