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

  • Статья

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

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 дважды, выполнив следующие действия:

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

Примеры

В следующем примере кода интерфейс 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 (включая Wudfddi.h)
DLL WUDFx.dll

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