Função GetFinalPathNameByHandleW (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 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 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.

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

Valor retornado

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.

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

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-xxxxxxxx}\".

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

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

Requisitos

Confira também

Funções de gerenciamento de arquivos