Metode IWDFDevice2::CreateSymbolicLinkWithReferenceString (wudfddi.h)

Artikel
08/08/2023

[Peringatan: UMDF 2 adalah versi terbaru UMDF dan pengganti UMDF 1. Semua driver UMDF baru harus ditulis menggunakan UMDF 2. Tidak ada fitur baru yang ditambahkan ke UMDF 1 dan ada dukungan terbatas untuk UMDF 1 pada versi Windows 10 yang lebih baru. Driver Universal Windows harus menggunakan UMDF 2. Untuk informasi selengkapnya, lihat Mulai menggunakan UMDF.]

MetodeCreateSymbolicLinkWithReferenceString membuat nama tautan simbolis, dan secara opsional, string referensi, untuk perangkat

Sintaks

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

Parameter

[in] pSymbolicLink

Penunjuk ke string karakter yang dihentikan NULL yang menjadi nama perangkat yang terlihat pengguna. Nama tautan simbolis harus berada di namespace Layanan DosDevices global.

[in, optional] pReferenceString

Penunjuk ke string karakter yang dihentikan NULL yang ditambahkan Windows ke nama perangkat saat aplikasi menggunakan nama simbolis yang ditentukan parameter pSymbolicLink . Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini. Parameter ini bersifat opsional dan dapat berupa NULL.

Nilai kembali

CreateSymbolicLinkWithReferenceString mengembalikan S_OK jika operasi berhasil. Jika tidak, metode mungkin mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
E_INVALIDARG	Pemanggil menentukan nilai yang tidak valid untuk parameter input.
E_OUTOFMEMORY	Alokasi memori gagal.

Metode ini mungkin mengembalikan salah satu nilai lain yang dikandung Winerror.h.

Keterangan

CreateSymbolicLinkWithReferenceString membuat nama tautan simbolis, dan secara opsional string referensi, untuk perangkat yang diwakili antarmuka IWDFDevice2 . Setelah driver memanggil CreateSymbolicLinkWithReferenceString, aplikasi dapat menggunakan nama tautan simbolis untuk mengakses perangkat.

Misalkan nama perangkat Anda adalah "\Device\MyDevice". Anda dapat membuat nama tautan simbolis "DeviceUserName" untuk perangkat Anda dengan menentukan "L"DeviceUserName"" untuk parameter pSymbolicLink . Jika Anda menentukan "L"Instance3"" untuk parameter pReferenceString , Anda membuat tautan simbolis ke \Device\MyDevice\Instance3. Jika aplikasi membuka perangkat dengan menggunakan nama tautan simbolis, manajer I/O membuka \Device\MyDevice dan membuat objek file WDM yang berisi string \Instance3 sebagai nama file. Driver berbasis UMDF Anda menerima objek file yang dibuat kerangka kerja, yang juga berisi string \Instance3 sebagai nama file (lihat IWDFFile::RetrieveFileName).

Biasanya, alih-alih menyediakan tautan simbolis, driver berbasis kerangka kerja menyediakan antarmuka perangkat yang dapat digunakan aplikasi untuk mengakses perangkat mereka.

Jika perangkat dihapus secara tiba-tiba (dihapus dari kejutan), kerangka kerja akan menghapus tautan simbolis ke perangkat. Driver kemudian dapat menggunakan nama tautan simbolis untuk instans baru perangkat.

Jika Anda tidak perlu menambahkan string referensi ke nama tautan simbolis perangkat Anda, driver Anda dapat memanggil IWDFDevice::CreateSymbolicLink alih-alih CreateSymbolicLinkWithReferenceString.

Contoh

Baris berikut mendefinisikan awalan nama tautan simbolis di namespace Layanan DosDevices global.

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

Contoh kode berikut membuat string nama simbolis, mendapatkan antarmuka IWDFDevice2 , lalu memanggil 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);
    }

Persyaratan

Persyaratan	Nilai
Akhir dukungan	Tidak tersedia di UMDF 2.0 dan yang lebih baru.
Target Platform	Desktop
Versi UMDF minimum	1.9
Header	wudfddi.h (termasuk Wudfddi.h)
DLL	WUDFx.dll

Lihat juga

IWDFDevice2

IWDFDevice::CreateSymbolicLink

Bagikan melalui