Metode IWDFDevice::RetrieveDeviceName (wudfddi.h)

Artikel
03/01/2024

[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.]

Metode RetrieveDeviceName mengambil nama perangkat mode kernel yang mendasar.

Sintaks

HRESULT RetrieveDeviceName(
  [out]     PWSTR pDeviceName,
  [in, out] DWORD *pdwDeviceNameLength
);

Parameter

[out] pDeviceName

Penunjuk ke buffer yang menerima string yang dihentikan NULL yang mewakili nama perangkat mode kernel yang mendasar, jika buffer bukan NULL dan RetrieveDeviceName berhasil.

[in, out] pdwDeviceNameLength

Penunjuk ke variabel yang menerima jumlah karakter, termasuk karakter NULL , dalam nama perangkat.

Jika buffer di pDeviceName adalah NULL, nilai yang disediakan driver adalah nol. Kerangka kerja kemudian mengembalikan ukuran, dalam karakter, yang diperlukan untuk string nama perangkat.

Jika buffer di pDeviceNamenon-NULL, kerangka kerja mengembalikan ukuran, dalam karakter, dari string nama perangkat.

Nilai kembali

RetrieveDeviceName mengembalikan S_OK untuk skenario berikut:

Buffer yang ditunjuk oleh parameter pDeviceName adalah non-NULL dan cukup besar untuk menyimpan string nama, termasuk karakter NULL , dan kerangka kerja berhasil menyalin string ke dalam buffer yang disediakan dan mengatur variabel yang ditunjukkan oleh pdwDeviceNameLength ke jumlah karakter dalam string.
Buffer di pDeviceName adalah NULL, driver mengatur variabel di pdwDeviceNameLength ke 0, dan kerangka kerja mengatur variabel di pdwDeviceNameLength ke jumlah karakter yang diperlukan untuk string.

RetrieveDeviceName mengembalikan HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) untuk menunjukkan bahwa buffer yang disediakan bukan NULL dan tidak berisi cukup ruang untuk menahan nama perangkat. Kerangka kerja mengatur variabel di pdwDeviceNameLength ke jumlah karakter yang diperlukan untuk string.

RetrieveDeviceName mungkin juga mengembalikan nilai HRESULT lainnya.

Keterangan

Nama perangkat bukan nama objek perangkat fisik (PDO). Sebaliknya, nama perangkat adalah nama reflektor. Pengandar harus menargetkan semua I/O ke obyek perangkat ini.

Contoh

Contoh kode berikut menunjukkan cara mengambil nama perangkat mode kernel yang mendasar.

    PWSTR deviceName = NULL;
    DWORD deviceNameCch = 0;
    HRESULT hr;
    //
    // Get the length of the device name to allocate a buffer
    //
    hr = m_FxDevice->RetrieveDeviceName(NULL, &deviceNameCch);
    //
    // Allocate the buffer
    //
    deviceName = new WCHAR[deviceNameCch];

    if (deviceName == NULL) {
        hr = E_OUTOFMEMORY;
        goto Exit1;
    }
    //
    // Get the device name
    //
    hr = m_FxDevice->RetrieveDeviceName(deviceName,
                                        &deviceNameCch);

    // Open the device and get the handle

    m_Handle = CreateFile(deviceName, 
                         (GENERIC_READ | GENERIC_WRITE), 
                         0, 
                         NULL, 
                         OPEN_EXISTING, 
                         FILE_FLAG_OVERLAPPED, 
                         NULL);

Persyaratan

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

Lihat juga

IWDFDevice

Bagikan melalui