Função GetFullPathNameA (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 GetFullPathNameA(
[in] LPCSTR lpFileName,
[in] DWORD nBufferLength,
[out] LPSTR lpBuffer,
[out] LPSTR *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.
[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 atual 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 eles 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.
Nomes de compartilhamento e volume são entrada válida para lpFileName. Por exemplo, a lista a seguir identifica o caminho e os nomes de arquivo 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 na unidade "U:\"
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 para a frente.
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 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
| Requisito | Valor |
|---|---|
| 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
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, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de