GetFinalPathNameByHandleA 函数 (fileapi.h)

  • 项目

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

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

语法

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

参数

[in] hFile

文件或目录的句柄。

[out] lpszFilePath

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

[in] cchFilePath

lpszFilePath 的大小（以 TCHAR为单位）。 此值必须包含 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 接收的字符串的长度（以 TCHAR为单位）。 此值不包括终止 null 字符的大小。

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

如果函数因 lpszFilePath 太小而无法保存字符串加上终止 null 字符而失败，则返回值是所需的缓冲区大小（以 TCHAR为单位）。 此值包括终止 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) 是
群集共享卷文件系统 (CSV) 是
弹性文件系统 (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 应用]
目标平台 Windows
标头 fileapi.h (包括 Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

文件管理函数