Método IWDFFile2::RetrieveCountedFileName (wudfddi.h)

Artigo
02/07/2025

Aviso

O 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 aoUMDF.

O método RetrieveCountedFileName recupera o nome de arquivo contado completo para um arquivo associado a um dispositivo.

Sintaxe

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

Parâmetros

[out] pCountedFileName

Um ponteiro para um buffer alocado pelo chamador. Esse buffer recebe um NULL cadeia de caracteres terminada que representa o nome completo do arquivo associado ao dispositivo. Se o ponteiro for NULL, RetrieveCountedFileName recuperará apenas o comprimento da cadeia de caracteres.

[in, out] pdwCountedFileNameLengthInChars

Um ponteiro para uma variável alocada por chamador. Na entrada, o driver define a variável como o comprimento, em caracteres, do buffer ao qual pdwCountedFileNameLengthInChars pontos. Na saída, a estrutura define a variável como o comprimento, em caracteres, da cadeia de caracteres (incluindo a terminação caractere NULL) que ela colocou no buffer. Se um nome de arquivo contado não existir, a estrutura definirá a variável como zero.

Valor de retorno

RetrieveCountedFileName retornará S_OK se a operação for bem-sucedida. Caso contrário, o método poderá retornar um dos seguintes valores:

Código de retorno	Descrição
E_POINTER	O ponteiro pdwCountedFileNameLength é NULL.
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)	O nome do arquivo contado é inválido.
E_NOT_SUFFICIENT_BUFFER	O buffer para o qual pCountedFileName aponta é muito pequeno.

Esse método pode retornar um dos outros valores em Winerror.h.

Observações

Um nome de arquivo contado é uma cadeia de caracteres que pode incluir caracteres NULL ('\0') inseridos, além de uma NULLterminante. Para obter uma cadeia de caracteres de nome sem caracteres NULL, os drivers podem chamar IWDFFile::RetrieveFileName.

Normalmente, um driver chama RetrieveCountedFileName duas vezes, usando as seguintes etapas:

O driver chama RetrieveCountedFileName com o parâmetro pCountedFileName definido como NULL, para obter o comprimento do buffer necessário.
O driver aloca um buffer do tamanho necessário.
O driver chama RetrieveCountedFileName novamente para obter a cadeia de caracteres de nome de arquivo.

Exemplos

O exemplo de código a seguir obtém a interface IWDFFile2 da interface IWDFFile que a função de retorno de chamada IQueueCallbackCreate::OnCreateFile de um driver recebe. O exemplo chama RetrieveCountedFileName duas vezes; uma vez para obter o tamanho do nome do arquivo e uma vez para recuperar a cadeia de caracteres de nome de arquivo.

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

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.9
cabeçalho	wudfddi.h (inclua Wudfddi.h)
de DLL	WUDFx.dll

Consulte também

IWDFFile2
IWDFFile::RetrieveFileName

Compartilhar via