getFullPathNameA 函数 (fileapi.h)
检索指定文件的完整路径和文件名。
若要以事务处理操作的形式执行此操作，请使用 GetFullPathNameTransacted 函数。
有关文件和路径名称的详细信息，请参阅 文件名、路径和命名空间。
语法
DWORD GetFullPathNameA(
[in] LPCSTR lpFileName,
[in] DWORD nBufferLength,
[out] LPSTR lpBuffer,
[out] LPSTR *lpFilePart
);
参数
[in] lpFileName
文件的名称。
此参数可以是短 (8.3 格式) 或长文件名。 此字符串也可以是共享或卷名称。
[in] nBufferLength
要接收驱动器和路径的以 null 结尾的字符串的缓冲区的大小（以 TCHAR 为单位）。
[out] lpBuffer
指向缓冲区的指针，该缓冲区接收驱动器和路径的以 null 结尾的字符串。
[out] lpFilePart
指向缓冲区的指针，该缓冲区接收路径中最终文件名组件的 lpBuffer) 内的地址 (。
此参数可以为 NULL。
如果 lpBuffer 引用目录而不是文件， 则 lpFilePart 接收零。
返回值
如果函数成功，则返回值为复制到 lpBuffer 的字符串的长度（以 TCHAR 为单位），不包括终止 null 字符。
如果 lpBuffer 缓冲区太小而无法包含路径，则返回值是保存路径所需的缓冲区的大小（以 TCHAR 为单位），以及终止 null 字符。
如果函数因任何其他原因而失败，则返回值为零。 要获得更多的错误信息，请调用 GetLastError。
注解
GetFullPathName 将当前驱动器和目录的名称与指定的文件名合并，以确定指定文件的完整路径和文件名。 它还计算完整路径和文件名的文件名部分的地址。
此函数不会验证生成的路径和文件名是否有效，或者它们是否在关联的卷上看到了现有文件。
请注意， lpFilePart 参数不需要字符串缓冲区空间，但只需要一个地址。 这是因为它只是返回 lpBuffer 已存在的缓冲区中的地址。
共享和卷名称是 lpFileName 的有效输入。 例如，如果 test-2 是远程计算机，而 U： 是网络映射驱动器，其当前目录是卷的根目录，则以下列表标识返回的路径和文件名：
- 如果指定“\\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) | 是 |
| 群集共享卷文件系统 (CSV) | 是 |
| 弹性文件系统 (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 |