通过

GetFinalPathNameByHandleA 函数 （fileapi.h）

  • 项目

检索指定文件的最终路径。

有关文件和路径名称的详细信息，请参阅 命名文件。

语法

DWORD GetFinalPathNameByHandleA(
  [in]  HANDLE hFile,
  [out] LPSTR  lpszFilePath,
  [in]  DWORD  cchFilePath,
  [in]  DWORD  dwFlags
);

参数

[in] hFile

文件或目录的句柄。

[out] lpszFilePath

指向接收 hFile路径的缓冲区的指针。

[in] cchFilePath

TCHARlpszFilePath的大小。 此值必须包含 NULL 终止字符。

[in] dwFlags

要返回的结果的类型。 此参数可以是下列值之一。

价值 意义
FILE_NAME_NORMALIZED
0x0
 返回规范化驱动器名称。 这是默认值。
FILE_NAME_OPENED
0x8
 返回打开的文件名（未规范化）。
 

此参数还可以包括以下值之一。

价值 意义
VOLUME_NAME_DOS
0x0
 返回带驱动器号的路径。 这是默认值。
VOLUME_NAME_GUID
0x1
 返回卷的路径 GUID 路径而不是驱动器名称。
VOLUME_NAME_NONE
0x4
 返回没有驱动器信息的路径。
VOLUME_NAME_NT
0x2
 返回具有卷设备路径的路径。

返回值

如果函数成功，则返回值是 lpszFilePath接收的字符串的长度，TCHARs。 此值不包括终止 null 字符的大小。

Windows Server 2008 和 Windows Vista：对于此函数的 ANSI 版本，GetFinalPathNameByHandleA，返回值包括终止 null 字符的大小。

如果函数由于 lpszFilePath 太小而无法保存字符串和终止 null 字符，则返回值是所需的缓冲区大小，TCHARs。 此值包括终止 null 字符的大小。

如果函数因任何其他原因而失败，则返回值为零。 若要获取扩展的错误信息，请调用 GetLastError。

返回代码 描述
ERROR_PATH_NOT_FOUND
 如果要搜索驱动器号且不存在驱动器号，则可以返回该驱动器号。 例如，该句柄在当前未装载的驱动器上打开，或者创建卷且未为其分配驱动器号。 如果卷没有驱动器号，则可以使用卷 GUID 路径来标识它。

如果要在网络共享上搜索卷 GUID 路径，也可以返回此返回值。 不会为网络共享创建卷 GUID 路径。
ERROR_NOT_ENOUGH_MEMORY
 内存不足，无法完成操作。
ERROR_INVALID_PARAMETER
 为 dwFlags指定了无效标志。

言论

服务器消息块 （SMB） 协议不支持对规范化路径的查询。 因此，当调用此函数时，使用 SMB 和 FILE_NAME_NORMALIZED 标志传递打开的文件句柄时，该函数会将路径拆分为其组件，并尝试依次查询每个组件的规范化名称。 如果用户缺少对这些组件中的任何一个组件的访问权限，则函数调用会失败并ERROR_ACCESS_DENIED。

最后一个路径是完全解析路径时返回的路径。 例如，对于指向“D：\yourdir”的名为“C：\tmp\mydir”的符号链接，最终路径为“D：\yourdir”。

此函数返回的字符串使用“\\？\”语法。 有关详细信息，请参阅 CreateFile。

在 Windows 8 和 Windows Server 2012 中，以下技术支持此函数。

科技 支持
服务器消息块 （SMB） 3.0 协议 是的
SMB 3.0 透明故障转移 （TFO） 是的
具有横向扩展文件共享的 SMB 3.0 （SO） 是的
群集共享卷文件系统 （CsvFS） 是的
可复原文件系统 （ReFS） 是的
 

例子

以下示例演示如何使用 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);
}

注意

fileapi.h 标头将 GetFinalPathNameByHandle 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的 约定。

要求

要求 价值
最低支持的客户端 Windows Vista [桌面应用 |UWP 应用]
支持的最低服务器 Windows Server 2008 [桌面应用 |UWP 应用]
目标平台 窗户
标头 fileapi.h （包括 Windows.h）
库 Kernel32.lib
DLL Kernel32.dll

另请参阅

文件管理功能