Метод IWDFFile::RetrieveFileName (wudfddi.h)

Статья
02/07/2025

[ предупреждение: UMDF 2 является последней версией UMDF и заменяет UMDF 1. Все новые драйверы UMDF должны быть написаны с помощью UMDF 2. Новые функции не добавляются в UMDF 1, а поддержка UMDF 1 в более новых версиях Windows 10 ограничена. Универсальные драйверы Windows должны использовать UMDF 2. Дополнительные сведения см. в разделе Начало работы с UMDF.]

Метод RetrieveFileName извлекает полное имя файла, связанного с базовым устройством в режиме ядра.

Синтаксис

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

Параметры

[out] pFileName

Указатель на предоставленный вызывающим буфером, который получает строку NULL-terminated, представляющую полное имя файла, связанного с базовым устройством режима ядра, если указанный указатель не являетсяNULL и RetrieveFileName успешно.

[in, out] pdwFileNameLengthInChars

Указатель на указанную вызывающим переменную, которая получает размер в символах полного имени файла, на которое pFileName указывает. Если буфер в pFileName не являетсяNULL, платформа возвращает размер строки имени файла в символах.

При входных данных драйвер устанавливает эту переменную в размер в символах буфера, на который pFileName указывает. Если драйвер предоставляет null для pFileName и ноль для переменной, pdwFileNameLengthInChars указывает, что платформа задает переменную размеру в символах, требуемую строкой имени файла.

Возвращаемое значение

RetrieveFileName возвращает S_OK для следующих сценариев:

Буфер, на который указывает параметр pFileName, неnull и достаточно большой для хранения строки имени, включая символ NULL, а платформа успешно скопировала строку в предоставленный буфер и задайте переменную, на которую указывает pdwFileNameLengthInChars число символов в строке.
Буфер на pFileName был NULL, драйвер предустановил переменную в pdwFileNameLengthInChars значение 0, а платформа задает переменную в pdwFileNameLengthInChars число символов, необходимых для строки.

RetrieveFileName возвращает HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER), чтобы указать, что предоставленный буфер не являетсяNULL и не содержал достаточно места для хранения имени файла. Платформа задает переменную в pdwFileNameLengthInChars число символов, необходимых для строки.

RetrieveFileName также может возвращать другие значения HRESULT.

Замечания

Драйвер может вызвать функцию обратного вызова RetrieveFileName из функции обратного вызова IQueueCallbackCreate::OnCreateFile обратного вызова. Дополнительные сведения см. в разделе Использование интерфейсов устройств в драйверах UMDF.

Примеры

В следующем примере кода показано, как получить имя файла.

    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);
    }

Требования

Требование	Ценность
завершение поддержки	Недоступно в UMDF 2.0 и более поздних версиях.
целевая платформа	Настольный
минимальная версия UMDF	1.5
заголовка	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

См. также

IWDFFile

Поделиться через