Método IWDFFile::RetrieveFileName (wudfddi.h)

Artigo
02/07/2025

[Aviso: UMDF 2 é a versão mais recente do UMDF e substitui o UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum recurso novo está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Os drivers universais do Windows devem usar o UMDF 2. Para obter mais informações, consulte Introdução aoda UMDF .]

O método RetrieveFileName recupera o nome completo do arquivo associado ao dispositivo de modo kernel subjacente.

Sintaxe

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

Parâmetros

[out] pFileName

Um ponteiro para um buffer fornecido pelo chamador que recebe um cadeia de caracteres nullterminada que representa o nome completo do arquivo associado ao dispositivo de modo kernel subjacente, se o ponteiro fornecido não for NULL e RetrieveFileName for bem-sucedido.

[in, out] pdwFileNameLengthInChars

Um ponteiro para uma variável fornecida pelo chamador que recebe o tamanho, em caracteres, do nome de arquivo completo para o qual pFileName aponta. Se o buffer em pFileName não forNULL, a estrutura retornará o tamanho, em caracteres, da cadeia de caracteres do nome do arquivo.

Na entrada, o driver define essa variável como o tamanho, em caracteres, do buffer para o qual pFileName aponta. Se o driver fornecer NULL para pFileName e zero para a variável que pdwFileNameLengthInChars aponta, a estrutura define a variável para o tamanho, em caracteres, que a cadeia de caracteres de nome de arquivo requer.

Valor de retorno

RetrieveFileName retorna S_OK para os seguintes cenários:

O buffer ao qual o parâmetro pFileName aponta era não NULL e grande o suficiente para manter a cadeia de caracteres de nome, incluindo o caractere NULL e a estrutura copiou com êxito a cadeia de caracteres para o buffer fornecido e definiu a variável que é apontada pelo parâmetro pdwFileNameLengthInChars para o número de caracteres na cadeia de caracteres.
O buffer em pFileName foi NULL, o driver predefini a variável em pdwFileNameLengthInChars como 0 e a estrutura definiu a variável em pdwFileNameLengthInChars para o número de caracteres necessários para a cadeia de caracteres.

RetrieveFileName retorna HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) para indicar que o buffer fornecido não é NULL e não continha espaço suficiente para manter o nome do arquivo. A estrutura define a variável em pdwFileNameLengthInChars para o número de caracteres necessários para a cadeia de caracteres.

RetrieveFileName também pode retornar outros valores HRESULT.

Observações

O driver pode chamar RetrieveFileName de sua função de retorno de chamada IQueueCallbackCreate::OnCreateFile. Para obter mais informações, consulte Usando interfaces de dispositivo em drivers UMDF.

Exemplos

O exemplo de código a seguir mostra como recuperar o nome de um arquivo.

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

Requisitos

Requisito	Valor
fim do suporte	Indisponível no UMDF 2.0 e posterior.
da Plataforma de Destino	Área de trabalho
versão mínima do UMDF	1.5
cabeçalho	wudfddi.h (inclua Wudfddi.h)
de DLL	WUDFx.dll

Consulte também

IWDFFile

Compartilhar via