Função GetFinalPathNameByHandleA (fileapi.h)

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 TCHARs. Esse valor deve incluir um caractere de terminação NULL .

[in] dwFlags

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

Valor Significado
FILE_NAME_NORMALIZED
0x0
Retornar 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.

Retornar valor

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ê criar um volume e não atribuir uma letra de unidade. Se um volume não tiver letra de unidade, você poderá usar o caminho guid de volume para identificá-lo.

Esse valor retornado também poderá ser retornado se você estiver procurando um caminho GUID de volume em um compartilhamento de rede. Caminhos guid 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.

Comentários

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. 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 Windows Server 2012, essa função é compatível com as tecnologias a seguir.

Tecnologia Com suporte
Protocolo SMB (SMB) 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 Clusterizado (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);
}

Observação

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 de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

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

Confira também

Funções de gerenciamento de arquivos