通过

getFinalPathNameByHandleW 函数 (fileapi.h)

  • 项目

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

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

语法

DWORD GetFinalPathNameByHandleW(
  [in]  HANDLE hFile,
  [out] LPWSTR 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
 返回打开的文件名， (未规范化) 。
 

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

Value 含义
VOLUME_NAME_DOS
0x0
 返回带有驱动器号的路径。 这是默认值。
VOLUME_NAME_GUID
0x1
 返回包含卷 GUID 路径的路径，而不是驱动器名称。
VOLUME_NAME_NONE
0x4
 返回没有驱动器信息的路径。
VOLUME_NAME_NT
0x2
 返回 NT 设备对象路径。

返回值

如果函数成功，则返回值为 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”。

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

使用 VOLUME_NAME_GUID 时，返回的路径将以格式为“\\？\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\”的卷 GUID 路径开头。

使用 VOLUME_NAME_NT 时，返回的路径适用于 NT 设备对象，并将以设备名称（如“\Device\HarddiskVolume1\”）开头。 这种类型的路径不能直接由 Windows 程序使用，因为它类似于相对路径。

某些第三方驱动程序可以在不使用装载管理器的情况下创建驱动器号或装入点。 如果未使用装载管理器创建驱动器，则 VOLUME_NAME_DOS 或 VOLUME_NAME_GUID 将不会成功;仅 VOLUME_NAME_NT 可用。 若要确定卷设备路径的驱动器号，请对每个驱动器号使用 QueryDosDevice 函数，直到找到匹配的设备名称。

在 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

另请参阅

文件管理函数