Metode IWDFFile::RetrieveFileName (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 RetrieveFileName mengambil nama lengkap file yang terkait dengan perangkat mode kernel yang mendasar.

Sintaks

HRESULT RetrieveFileName(
  [out]     PWSTR pFileName,
  [in, out] DWORD *pdwFileNameLengthInChars
);

Parameter

[out] pFileName

Penunjuk ke buffer yang disediakan penelepon yang menerima string yang dihentikan NULL yang mewakili nama lengkap file yang terkait dengan perangkat mode kernel yang mendasar, jika penunjuk yang disediakan non-NULL dan RetrieveFileName berhasil.

[in, out] pdwFileNameLengthInChars

Penunjuk ke variabel yang disediakan penelepon yang menerima ukuran, dalam karakter, dari nama file lengkap yang diunjukkan pFileName . Jika buffer di pFileName bukan NULL, kerangka kerja mengembalikan ukuran, dalam karakter, dari string nama file.

Pada input, driver mengatur variabel ini ke ukuran, dalam karakter, dari buffer yang dirujuk pFileName . Jika driver menyediakan NULL untuk pFileName dan nol untuk variabel yang dituju pdwFileNameLengthInChars , kerangka kerja mengatur variabel ke ukuran, dalam karakter, yang diperlukan string nama file.

Nilai kembali

RetrieveFileName mengembalikan S_OK untuk skenario berikut:

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

RetrieveFileName mengembalikan HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) untuk menunjukkan bahwa buffer yang disediakan bukan NULL dan tidak berisi cukup ruang untuk menyimpan nama file. Kerangka kerja mengatur variabel di pdwFileNameLengthInChars ke jumlah karakter yang diperlukan untuk string.

RetrieveFileName mungkin juga mengembalikan nilai HRESULT lainnya.

Keterangan

Driver Anda mungkin memanggil RetrieveFileName dari fungsi panggilan balik IQueueCallbackCreate::OnCreateFile . Untuk informasi selengkapnya, lihat Menggunakan Antarmuka Perangkat di Driver UMDF.

Contoh

Contoh kode berikut menunjukkan cara mengambil nama file.

    ULONG fileNameCch = 0;
    PWSTR fileName = NULL;
    ULONG index;

    CComObject<CUmdfHidFile> *file = NULL;

    HRESULT hr;

    // Get the length of the file name to allocate a buffer.
    hr = WdfFile->RetrieveFileName(NULL, &fileNameCch);
    //
    // Allocate the buffer.
    //
    if (SUCCEEDED(hr))
    {
        fileName = new WCHAR[fileNameCch];

        if (fileName == NULL)
        {
            hr = E_OUTOFMEMORY;
        }
    }
    //
    // Get the file name.
    //
    if (SUCCEEDED(hr))
    {
        hr = WdfFile->RetrieveFileName(fileName, &fileNameCch);
    }

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

IWDFFile

Bagikan melalui