Compartilhar via

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

  • Artigo

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 novo recurso 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 com UMDF.

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 uma cadeia de caracteres terminada em NULL 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 pelo chamador. Na entrada, o driver define a variável como o comprimento, em caracteres, do buffer ao qual pdwCountedFileNameLengthInChars aponta. Na saída, a estrutura define a variável como o comprimento, em caracteres, da cadeia de caracteres (incluindo o caractere NULL de terminação) que ela colocou no buffer. Se um nome de arquivo contado não existir, a estrutura definirá a variável como zero.

Retornar valor

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.

Comentários

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

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

  1. O driver chama RetrieveCountedFileName com o parâmetro pCountedFileName definido como NULL, para obter o comprimento do buffer necessário.
  2. O driver aloca um buffer do tamanho necessário.
  3. 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 comprimento 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.
Plataforma de Destino Área de Trabalho
Versão mínima do UMDF 1,9
Cabeçalho wudfddi.h (inclua Wudfddi.h)
DLL WUDFx.dll

Confira também