Metode IWDFFile2::RetrieveCountedFileName (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 Memulai UMDF.

Metode RetrieveCountedFileName mengambil nama file lengkap yang dihitung untuk file yang terkait dengan perangkat.

Sintaks

HRESULT RetrieveCountedFileName(
  [out]     WCHAR *pCountedFileName,
  [in, out] DWORD *pdwCountedFileNameLengthInChars
);

Parameter

[out] pCountedFileName

Penunjuk ke buffer yang dialokasikan penelepon. Buffer ini menerima string karakter null yang dihentikan yang mewakili nama lengkap file yang terkait dengan perangkat. Jika penunjuk ADALAH NULL, RetrieveCountedFileName hanya mengambil panjang string.

[in, out] pdwCountedFileNameLengthInChars

Penunjuk ke variabel yang dialokasikan penelepon. Pada input, driver mengatur variabel ke panjang, dalam karakter, dari buffer tempat pdwCountedFileNameLengthInChars menunjuk. Pada output, kerangka kerja mengatur variabel ke panjang, dalam karakter, dari string karakter (termasuk karakter NULL yang mengakhiri) yang ditempatkan di buffer. Jika nama file yang dihitung tidak ada, kerangka kerja mengatur variabel ke nol.

Nilai kembali

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

Menampilkan kode	Deskripsi
E_POINTER	Penunjuk pdwCountedFileNameLength adalah NULL.
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)	Nama file yang dihitung tidak valid.
E_NOT_SUFFICIENT_BUFFER	Buffer yang dituju pCountedFileName terlalu kecil.

Metode ini mungkin mengembalikan salah satu nilai lain di Winerror.h.

Keterangan

Nama file yang dihitung adalah string yang dapat menyertakan karakter NULL ('\0') yang disematkan selain NULL yang mengakhiri. Untuk mendapatkan string nama tanpa karakter NULL yang disematkan, driver dapat memanggil IWDFFile::RetrieveFileName.

Biasanya, driver memanggil RetrieveCountedFileName dua kali, menggunakan langkah-langkah berikut:

Driver memanggil RetrieveCountedFileName dengan parameter pCountedFileName diatur ke NULL, untuk mendapatkan panjang buffer yang diperlukan.
Driver mengalokasikan buffer dengan ukuran yang diperlukan.
Driver memanggil RetrieveCountedFileName lagi untuk mendapatkan string nama file.

Contoh

Contoh kode berikut mendapatkan antarmuka IWDFFile2 dari antarmuka IWDFFile yang diterima fungsi panggilan balik IQueueCallbackCreate::OnCreateFile driver. Contoh memanggil RetrieveCountedFileName dua kali; sekali untuk mendapatkan panjang nama file dan sekali untuk mengambil string nama file.

VOID
STDMETHODCALLTYPE
CMyQueue::OnCreateFile(
    __in IWDFIoQueue *pWdfQueue,
    __in IWDFIoRequest *pWdfRequest,
    __in IWDFFile*  pWdfFileObject
    )
 ...
    IWDFFile2*  pWdfFileObject2 = NULL;
    WCHAR*  countedFileName = NULL;
    DWORD  countedFileNameCch = 0;
    HRESULT  hr = S_OK;
 
    //
    // Obtain IWDFFile2 interface from IWDFFile.
    //
    hr = pWdfFileObject->QueryInterface(IID_PPV_ARGS(&pWdfFileObject2));
    if (!SUCCEEDED(hr))
    {
        goto Done;
    }
    //
    // Get length of counted filename.
    //
    hr = pWdfFileObject2->RetrieveCountedFileName(NULL,
                                                  &countedFileNameCch);
    if (!SUCCEEDED(hr))
    {
        goto Done;
    }
    if (countedFileNameCch != 0)
    {
        //
        // Allocate a buffer.
        //
        countedFileName = new WCHAR[countedFileNameCch];
        if (countedFileName == NULL)
        {
            hr = E_OUTOFMEMORY;
            goto Done;
        }
        //
        // Get counted file name.
        //
        hr = pWdfFileObject2->RetrieveCountedFileName(countedFileName, 
                                                      &countedFileNameCch);
        if (!SUCCEEDED(hr))
        {
            goto Done;
        }
    }
    ...

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

Bagikan melalui