Função GetFullPathNameW (fileapi.h)
Recupera o caminho completo e o nome do arquivo especificado.
Para executar essa operação como uma operação transacionada, use a função GetFullPathNameTransacted .
Para obter mais informações sobre nomes de arquivo e caminho, consulte Nomes de arquivo, caminhos e namespaces.
Sintaxe
DWORD GetFullPathNameW(
[in] LPCWSTR lpFileName,
[in] DWORD nBufferLength,
[out] LPWSTR lpBuffer,
[out] LPWSTR *lpFilePart
);
Parâmetros
[in] lpFileName
O nome do arquivo.
Esse parâmetro pode ser curto (o formulário 8.3) ou um nome de arquivo longo. Essa cadeia de caracteres também pode ser um nome de compartilhamento ou volume.
Por padrão, o nome é limitado a MAX_PATH caracteres. Para estender esse limite para 32.767 caracteres largos, acrescente "\\?\" ao caminho. Para obter mais informações, confira Nomear arquivos, caminhos e namespaces.
Dica
A partir do Windows 10, versão 1607, você pode optar por remover a limitação de MAX_PATH sem acrescentar "\\?\". Consulte a seção "Limitação máxima do comprimento do caminho" de Arquivos de Nomenclatura, Caminhos e Namespaces para obter detalhes.
[in] nBufferLength
O tamanho do buffer para receber a cadeia de caracteres terminada em nulo para a unidade e o caminho, em TCHARs.
[out] lpBuffer
Um ponteiro para um buffer que recebe a cadeia de caracteres terminada em nulo para a unidade e o caminho.
[out] lpFilePart
Um ponteiro para um buffer que recebe o endereço (dentro de lpBuffer) do componente de nome de arquivo final no caminho.
Este parâmetro pode ser NULL.
Se lpBuffer se referir a um diretório e não a um arquivo, lpFilePart receberá zero.
Retornar valor
Se a função for bem-sucedida, o valor retornado será o comprimento, em TCHARs, da cadeia de caracteres copiada para lpBuffer, sem incluir o caractere nulo de terminação.
Se o buffer lpBuffer for muito pequeno para conter o caminho, o valor retornado será o tamanho, em TCHARs, do buffer necessário para manter o caminho e o 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
GetFullPathName mescla o nome da unidade e do diretório atuais com um nome de arquivo especificado para determinar o caminho completo e o nome do arquivo de um arquivo especificado. Ele também calcula o endereço da parte do nome do arquivo do caminho completo e do nome do arquivo.
Essa função não verifica se o caminho resultante e o nome do arquivo são válidos ou se veem um arquivo existente no volume associado.
Observe que o parâmetro lpFilePart não requer espaço de buffer de cadeia de caracteres, mas apenas o suficiente para um único endereço. Isso ocorre porque ele simplesmente retorna um endereço dentro do buffer que já existe para lpBuffer.
Os nomes de compartilhamento e volume são entradas válidas para lpFileName. Por exemplo, a lista a seguir identifica os nomes de arquivo e caminho retornados se test-2 for um computador remoto e U: é uma unidade mapeada de rede cujo diretório atual é a raiz do volume:
- Se você especificar "\\test-2\q$\lh", o caminho retornado será "\\test-2\q$\lh"
- Se você especificar "\\?\UNC\test-2\q$\lh", o caminho retornado será "\\?\UNC\test-2\q$\lh"
- Se você especificar "U:" o caminho retornado será o diretório atual no "U:\" Dirigir
Se o valor retornado for maior ou igual ao valor especificado em nBufferLength, você poderá chamar a função novamente com um buffer grande o suficiente para manter o caminho. Para obter um exemplo desse caso, além de usar o buffer de comprimento zero para alocação dinâmica, consulte a seção Código de exemplo.
Os caminhos relativos passados para a função GetFullPathName são interpretados como relativos ao diretório atual do processo. O estado do diretório atual escrito pela função SetCurrentDirectory é global para o processo e pode ser alterado por qualquer thread a qualquer momento. Os aplicativos devem estar cientes de que chamadas consecutivas para a função GetFullPathName com um caminho relativo podem produzir resultados diferentes se o diretório atual for alterado entre as duas chamadas.
Para evitar problemas causados por resultados inconsistentes, aplicativos multithread e código de biblioteca compartilhada devem evitar o uso de caminhos relativos. Se um caminho relativo for recebido, ele deverá ser consumido exatamente uma vez, passando o caminho relativo diretamente para uma função como CreateFile ou convertendo-o em um caminho absoluto e usando o caminho absoluto desse ponto em diante.
Em Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.
Tecnologia | Com suporte |
---|---|
Protocolo SMB 3.0 | Sim |
TFO (Failover Transparente) do SMB 3.0 | Sim |
SMB 3.0 com compartilhamentos de arquivos de expansão (SO) | Sim |
CsvFS (Sistema de Arquivos de Volume Compartilhado clusterizado) | Sim |
ReFS (Sistema de Arquivos Resiliente) | Sim |
Exemplos
O exemplo C++ a seguir mostra um uso básico de GetFullPathName, GetLongPathName e GetShortPathName. Para obter outro exemplo usando alocação dinâmica, consulte GetShortPathName.
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#define BUFSIZE 4096
#define LONG_DIR_NAME TEXT("c:\\longdirectoryname")
void _tmain(int argc, TCHAR *argv[])
{
DWORD retval=0;
BOOL success;
TCHAR buffer[BUFSIZE]=TEXT("");
TCHAR buf[BUFSIZE]=TEXT("");
TCHAR** lppPart={NULL};
if( argc != 2 )
{
_tprintf(TEXT("Usage: %s [file]\n"), argv[0]);
return;
}
// Retrieve the full path name for a file.
// The file does not need to exist.
retval = GetFullPathName(argv[1],
BUFSIZE,
buffer,
lppPart);
if (retval == 0)
{
// Handle an error condition.
printf ("GetFullPathName failed (%d)\n", GetLastError());
return;
}
else
{
_tprintf(TEXT("The full path name is: %s\n"), buffer);
if (lppPart != NULL && *lppPart != 0)
{
_tprintf(TEXT("The final component in the path name is: %s\n"), *lppPart);
}
}
// Create a long directory name for use with the next two examples.
success = CreateDirectory(LONG_DIR_NAME,
NULL);
if (!success)
{
// Handle an error condition.
printf ("CreateDirectory failed (%d)\n", GetLastError());
return;
}
// Retrieve the short path name.
retval = GetShortPathName(LONG_DIR_NAME,
buf,
BUFSIZE);
if (retval == 0)
{
// Handle an error condition.
printf ("GetShortPathName failed (%d)\n", GetLastError());
return;
}
else _tprintf(TEXT("The short name for %s is %s\n"),
LONG_DIR_NAME, buf);
// Retrieve the long path name.
retval = GetLongPathName(buf,
buffer,
BUFSIZE);
if (retval == 0)
{
// Handle an error condition.
printf ("GetLongPathName failed (%d)\n", GetLastError());
return;
}
else _tprintf(TEXT("The long name for %s is %s\n"), buf, buffer);
// Clean up the directory.
success = RemoveDirectory(LONG_DIR_NAME);
if (!success)
{
// Handle an error condition.
printf ("RemoveDirectory failed (%d)\n", GetLastError());
return;
}
}
Observação
O cabeçalho fileapi.h define GetFullPathName 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
Cliente mínimo com suporte | Windows XP [aplicativos da área de trabalho | Aplicativos UWP] |
Servidor mínimo com suporte | Windows Server 2003 [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
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de