Função GetFinalPathNameByHandleW (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 GetFinalPathNameByHandleW(
  [in]  HANDLE hFile,
  [out] LPWSTR 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 do objeto do dispositivo NT.

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".

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

Ao usar VOLUME_NAME_GUID, o caminho retornado começará com um caminho GUID de volume formatado como "\\?\Volume{xxxxxxx-xxxx-xxxx-xxxx-xxxx-xxxxxx}\".

Ao usar VOLUME_NAME_NT, o caminho retornado é para um objeto de dispositivo NT e começará com um nome de dispositivo como "\Device\HarddiskVolume1\". Esse tipo de caminho não pode ser usado diretamente por programas do Windows, pois se assemelha a um caminho relativo.

Alguns drivers de terceiros podem criar uma letra de unidade ou um ponto de montagem sem usar o Mount Manager. Se o Mount Manager não tiver sido usado para criar a unidade, VOLUME_NAME_DOS ou VOLUME_NAME_GUID não terá êxito; somente VOLUME_NAME_NT estará disponível. Para determinar a letra da unidade para o caminho do dispositivo de volume, use a função QueryDosDevice em cada letra da unidade até que um nome de dispositivo correspondente seja encontrado.

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