GetFullPathNameA 函数 (fileapi.h)
检索指定文件的完整路径和文件名。
若要将此操作作为事务处理操作执行，请使用 GetFullPathNameTransacted 函数。
有关文件和路径名称的详细信息，请参阅 文件名、路径和命名空间。
语法
DWORD GetFullPathNameA(
[in] LPCSTR lpFileName,
[in] DWORD nBufferLength,
[out] LPSTR lpBuffer,
[out] LPSTR *lpFilePart
);
参数
[in] lpFileName
文件的名称。
此参数可以是短 (8.3 窗体) 或长文件名。 此字符串也可以是共享或卷名称。
在此函数的 ANSI 版本中，名称限制为 MAX_PATH 个字符。 若要将此限制扩展到 32，767 宽字符，请调用函数的 Unicode 版本 (GetFullPathNameW) 。
[in] nBufferLength
要接收 TCHAR 中驱动器和路径的以 null 结尾的字符串的缓冲区大小。
[out] lpBuffer
指向接收驱动器和路径以 null 结尾的字符串的缓冲区的指针。
[out] lpFilePart
指向缓冲区的指针，该缓冲区在路径中最终文件名组件的 lpBuffer) 内接收地址 (。
此参数可以为 NULL。
如果 lpBuffer 引用目录而不是文件， 则 lpFilePart 接收零。
返回值
如果函数成功，则返回值为复制到 lpBuffer 的字符串的长度（以 TCHAR 为单位），不包括终止 null 字符。
如果 lpBuffer 缓冲区太小而不能包含路径，则返回值是缓冲区的大小（以 TCHAR 为单位），该缓冲区需要保留路径和终止 null 字符。
如果函数因任何其他原因而失败，则返回值为零。 要获得更多的错误信息，请调用 GetLastError。
注解
GetFullPathName 将当前驱动器和目录的名称与指定的文件名合并，以确定指定文件的完整路径和文件名。 它还计算完整路径和文件名的文件名部分的地址。
此函数不验证生成的路径和文件名是否有效，或者它们看到关联卷上的现有文件。
请注意， lpFilePart 参数不需要字符串缓冲区空间，但只足够用于单个地址。 这是因为它只返回已存在 lpBuffer 的缓冲区中的地址。
共享和卷名称是 lpFileName 的有效输入。 例如，如果 test-2 是远程计算机，则以下列表标识返回的路径和文件名：是网络映射驱动器，其当前目录是卷的根目录：
- 如果指定“\\test-2\q$\lh”，则返回的路径为“\\test-2\q$\lh”
- 如果指定“\\？\UNC\test-2\q$\lh”，则返回的路径为“\\？\UNC\test-2\q$\lh”
- 如果指定“U：”，则返回的路径是“U：\”上的当前目录驱动
如果返回值大于或等于 nBufferLength 中指定的值，则可以再次调用具有足够大的缓冲区来保存路径的函数。 有关此示例，除了使用零长度缓冲区进行动态分配外，请参阅“示例代码”部分。
传递给 GetFullPathName 函数的相对路径将解释为相对于进程的当前目录。 SetCurrentDirectory 函数编写的当前目录状态是进程的全局状态，随时可由任何线程更改。 应用程序应注意，如果当前目录在两次调用之间发生更改，则对具有相对路径的 GetFullPathName 函数的连续调用可能会产生不同的结果。
为了避免因结果不一致而导致的问题，多线程应用程序和共享库代码应避免使用相对路径。 如果收到相对路径，应仅使用一次，方法是将相对路径直接传递到 CreateFile 等函数，或者将其转换为绝对路径并使用从该点向前的绝对路径。
在Windows 8和Windows Server 2012中，以下技术支持此函数。
| 技术 | 支持 |
|---|---|
| 服务器消息块 (SMB) 3.0 协议 | 是 |
| SMB 3.0 透明故障转移 (TFO) | 是 |
| 具有横向扩展文件共享的 SMB 3.0 (SO) | 是 |
| 群集共享卷文件系统 (CsvFS) | 是 |
| 弹性文件系统 (ReFS) | 是 |
示例
以下 C++ 示例演示 了 GetFullPathName、 GetLongPathName 和 GetShortPathName 的基本用法。 有关使用动态分配的另一个示例，请参阅 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;
}
}
注意
fileapi.h 标头将 GetFullPathName 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非中性编码别名与非编码中性代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅 函数原型的约定。
要求
| 最低受支持的客户端 | Windows XP [桌面应用|UWP 应用] |
| 最低受支持的服务器 | Windows Server 2003 [桌面应用|UWP 应用] |
| 目标平台 | Windows |
| 标头 | fileapi.h (包括 Windows.h) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |