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

Статья
08/08/2023

[Предупреждение: 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, представляющую полное имя файла, связанного с базовым устройством режима ядра, если предоставленный указатель не равен 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 (включая Wudfddi.h)
DLL	WUDFx.dll

См. также раздел

IWDFFile

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