Função GetFinalPathNameByHandleA (fileapi.h)

Artigo
11/20/2024

Recupera o caminho final do arquivo especificado.

Para obter mais informações sobre nomes de arquivo e caminho, consulte Nomeando um arquivo.

Sintaxe

DWORD GetFinalPathNameByHandleA(
  [in]  HANDLE hFile,
  [out] LPSTR  lpszFilePath,
  [in]  DWORD  cchFilePath,
  [in]  DWORD  dwFlags
);

Parâmetros

[in] hFile

Um identificador para um arquivo ou diretório.

[out] lpszFilePath

Um ponteiro para um buffer que recebe o caminho de hFile.

[in] cchFilePath

O tamanho de lpszFilePath, em TCHAR. Esse valor deve incluir um caractere de terminação NULL.

[in] dwFlags

O tipo de resultado a ser retornado. Esse parâmetro pode ser um dos valores a seguir.

Valor	Significado
FILE_NAME_NORMALIZED 0x0	Retorne o nome da unidade normalizada. Esse é o padrão.
FILE_NAME_OPENED 0x8	Retornar o nome do arquivo aberto (não normalizado).

Esse parâmetro também pode incluir um dos valores a seguir.

Valor	Significado
VOLUME_NAME_DOS 0x0	Retorne o caminho com a letra da unidade. Esse é o padrão.
VOLUME_NAME_GUID 0x1	Retorne o caminho com um caminho GUID de volume em vez do nome da unidade.
VOLUME_NAME_NONE 0x4	Retorne o caminho sem informações de unidade.
VOLUME_NAME_NT 0x2	Retorne o caminho com o caminho do dispositivo de volume.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será o comprimento da cadeia de caracteres recebida por lpszFilePath, em TCHARs. Esse valor não inclui o tamanho do caractere nulo de terminação.

Windows Server 2008 e Windows Vista: Para a versão ANSI dessa função, GetFinalPathNameByHandleA, o valor retornado inclui o tamanho do caractere nulo de terminação.

Se a função falhar porque lpszFilePath é muito pequeno para manter a cadeia de caracteres mais o caractere nulo de terminação, o valor retornado será o tamanho do buffer necessário, em TCHARs. Esse valor inclui o tamanho do caractere nulo de terminação.

Se a função falhar por qualquer outro motivo, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Código de retorno	Descrição
ERROR_PATH_NOT_FOUND	Pode ser retornado se você estiver procurando uma letra de unidade e uma não existir. Por exemplo, o identificador foi aberto em uma unidade que não está montada no momento ou se você cria um volume e não atribui uma letra de unidade. Se um volume não tiver letra de unidade, você poderá usar o de volume GUID caminho para identificá-lo. Esse valor retornado também poderá ser retornado se você estiver procurando um volume GUID caminho em um compartilhamento de rede. Os caminhos de guid de de volume não são criados para compartilhamentos de rede.
ERROR_NOT_ENOUGH_MEMORY	Memória insuficiente para concluir a operação.
ERROR_INVALID_PARAMETER	Sinalizadores inválidos foram especificados para dwFlags.

Observações

O Protocolo SMB (Bloco de Mensagens do Servidor) não dá suporte a consultas para caminhos normalizados. Consequentemente, quando você chama essa função passando o identificador de um arquivo aberto usando SMB e, com o sinalizador FILE_NAME_NORMALIZED, a função divide o caminho em seus componentes e tenta consultar o nome normalizado de cada um desses componentes por sua vez. Se o usuário não tiver permissão de acesso a qualquer um desses componentes, a chamada de função falhará com ERROR_ACCESS_DENIED.

Um caminho final é o caminho retornado quando um caminho é totalmente resolvido. Por exemplo, para um link simbólico chamado "C:\tmp\mydir" que aponta para "D:\yourdir", o caminho final seria "D:\yourdir".

A cadeia de caracteres retornada por essa função usa a sintaxe "\\?\". Para obter mais informações, consulte CreateFile.

No Windows 8 e no Windows Server 2012, essa função é compatível com as tecnologias a seguir.

Tecnologia	Suportado
Protocolo SMB (Bloco de Mensagens do Servidor) 3.0	Sim
TFO (Failover Transparente) do SMB 3.0	Sim
SMB 3.0 com Compartilhamentos de Arquivos de Expansão (SO)	Sim
Sistema de Arquivos de Volume Compartilhado de Cluster (CsvFS)	Sim
ReFS (Sistema de Arquivos Resiliente)	Sim

Exemplos

O exemplo a seguir demonstra o uso da função GetFinalPathNameByHandle .

#include <windows.h>
#include <tchar.h>
#include <stdio.h>

#define BUFSIZE MAX_PATH

void __cdecl _tmain(int argc, TCHAR *argv[])
{
    TCHAR Path[BUFSIZE];
    HANDLE hFile;
    DWORD dwRet;

    printf("\n");
    if( argc != 2 )
    {
        printf("ERROR:\tIncorrect number of arguments\n\n");
        printf("%s <file_name>\n", argv[0]);
        return;
    }

    hFile = CreateFile(argv[1],               // file to open
                       GENERIC_READ,          // open for reading
                       FILE_SHARE_READ,       // share for reading
                       NULL,                  // default security
                       OPEN_EXISTING,         // existing file only
                       FILE_ATTRIBUTE_NORMAL, // normal file
                       NULL);                 // no attr. template

    if( hFile == INVALID_HANDLE_VALUE)
    {
        printf("Could not open file (error %d\n)", GetLastError());
        return;
    }

    dwRet = GetFinalPathNameByHandle( hFile, Path, BUFSIZE, VOLUME_NAME_NT );
    if(dwRet < BUFSIZE)
    {
        _tprintf(TEXT("\nThe final path is: %s\n"), Path);
    }
    else printf("\nThe required buffer size is %d.\n", dwRet);

    CloseHandle(hFile);
}

Nota

O cabeçalho fileapi.h define GetFinalPathNameByHandle como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	fileapi.h (inclua Windows.h)
biblioteca	Kernel32.lib
de DLL	Kernel32.dll

Consulte também

Funções de gerenciamento de arquivos

Compartilhar via