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

[Aviso: UMDF 2 é a versão mais recente do UMDF e substitui UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum novo recurso está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Drivers universais do Windows devem usar UMDF 2. Para obter mais informações, consulte Introdução com 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 uma cadeia de caracteres terminada em NULL que representa o nome completo do arquivo associado ao dispositivo de modo kernel subjacente, se o ponteiro fornecido for não 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 for NULL, a estrutura retornará o tamanho, em caracteres, da cadeia de caracteres de nome de 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 para a qual pdwFileNameLengthInChars aponta, a estrutura definirá a variável como o tamanho, em caracteres, que a cadeia de caracteres de nome de arquivo exigirá.

Retornar valor

RetrieveFileName retorna S_OK para os seguintes cenários:

• O buffer para o 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 era NULL, o driver predefiniva a variável em pdwFileNameLengthInChars como 0 e a estrutura definia a variável em pdwFileNameLengthInChars como 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 como o número de caracteres necessários para a cadeia de caracteres.

RetrieveFileName também pode retornar outros valores HRESULT.

Comentários

Seu 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.
Plataforma de Destino	Área de Trabalho
Versão mínima do UMDF	1.5
Cabeçalho	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

Confira também

IWDFFile