GetLongPathNameW 函数（fileapi.h）

项目
11/20/2024

将指定的路径转换为其长格式。

若要将此操作作为事务处理操作执行，请使用 GetLongPathNameTransacted 函数。

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

重要

若要使用此函数，调用方必须对指定的路径和父目录具有以下权限：

列出文件夹
读取数据
读取属性

语法

DWORD GetLongPathNameW(
  [in]  LPCWSTR lpszShortPath,
  [out] LPWSTR  lpszLongPath,
  [in]  DWORD   cchBuffer
);

参数

[in] lpszShortPath

要转换的路径。

默认情况下，名称限制为MAX_PATH个字符。若要将此限制扩展到 32,767 宽字符，请将“\\？\”前面追加到路径。有关详细信息，请参阅命名文件、路径和命名空间。

提示

从 Windows 10 版本 1607 开始，你可以选择加入以删除MAX_PATH限制，而无需追加“\\？\”。有关详细信息，请参阅命名文件、路径和命名空间的“最大路径长度限制”部分。

[out] lpszLongPath

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

可以使用用于 lpszShortPath 参数的缓冲区。

[in] cchBuffer

缓冲区的大小 lpszLongPath 指向 TCHAR。

返回值

如果函数成功，则返回值为复制到 lpszLongPath的字符串的长度（以 TCHAr为单位，不包括终止 null 字符）。

如果 lpBuffer 缓冲区太小而无法包含路径，则返回值为大小（TCHAR）是保存路径和终止 null 字符所需的缓冲区的大小。

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

言论

在许多文件系统上，短文件名包含波形符（~）字符。但是，并非所有文件系统都遵循此约定。因此，如果路径不包含波形符（~）字符，则不要假定可以跳过调用 GetLongPathName。

如果文件或目录存在但找不到长路径，GetLongPathName 成功，则已将 lpszShortPath 参数引用的字符串复制到 lpszLongPath 参数引用的缓冲区。

如果返回值大于 cchBuffer中指定的值，则可以使用足够大的缓冲区再次调用函数，以容纳路径。有关此示例的示例，请参阅 GetFullPathName的示例代码部分。

注意虽然本例中的返回值是包含终止 null 字符的长度，但成功返回值不包括计数中的终止 null 字符。

可以访问文件或目录，但无权访问该文件或目录的某些父目录。因此，当无法查询路径组件的父目录以确定该组件的长名称时，GetLongPathName 可能会失败。对于文件扩展名超过 3 个字符的目录组件，或者总长度超过 12 个字符，可以跳过此检查。有关详细信息，请参阅命名文件、路径和命名空间的短名称与长名称部分。

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

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

例子

有关使用 GetLongPathName的示例，请参阅 GetFullPathName的示例代码部分。

注意

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

要求

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