Метод IWDFFile2::RetrieveCountedFileName (wudfddi.h)

2025-02-07

Предупреждение

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

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

Синтаксис

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

Параметры

[out] pCountedFileName

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

[in, out] pdwCountedFileNameLengthInChars

Указатель на выделенную вызывающим переменную. При входных данных драйвер задает переменную длину в символах буфера, в котором pdwCountedFileNameLengthInChars точек. В выходных данных платформа задает переменную длину (в символах) строки символов (включая завершающийся символ null), который он помещается в буфер. Если имя файла не существует, платформа задает переменную нулевой.

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

RetrieveCountedFileName возвращает S_OK, если операция выполнена успешно. В противном случае метод может вернуть одно из следующих значений:

Возвращаемый код	Описание
E_POINTER	Указатель pdwCountedFileNameLength имеет значение NULL .
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)	Недопустимое имя файла с подсчетом.
E_NOT_SUFFICIENT_BUFFER	Буфер, на который pCountedFileName указывает слишком мало.

Этот метод может вернуть одно из других значений в Winerror.h.

Замечания

Числовое имя файла — это строка, которая может включать внедренные символы NULL (\0) в дополнение к концам NULL. Чтобы получить строку имени без внедренных символов NULL, драйверы могут вызывать IWDFFile::RetrieveFileName.

Как правило, драйвер вызывает RetrieveCountedFileName дважды, выполнив следующие действия:

Драйвер вызывает GetCountedFileName с параметром pCountedFileName значением NULL, чтобы получить необходимую длину буфера.
Драйвер выделяет буфер требуемого размера.
Драйвер снова вызывает GetCountedFileName, чтобы получить строку имени файла.

Примеры

Следующий пример кода получает интерфейс IWDFFile2 из интерфейса IWDFFile, который получает функция обратного вызова драйвера IQueueCallbackCreate::OnCreateFile обратного вызова. В примере вызывается RetrieveCountedFileName дважды; после получения длины файла и один раз, чтобы получить строку имени файла.

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

Требования

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

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