getShortPathNameW 函数 (fileapi.h)

项目
06/02/2023

检索指定路径的短路径格式。

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

语法

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

参数

[in] lpszLongPath

路径字符串。

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

提示

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

[out] lpszShortPath

指向缓冲区的指针，用于接收 lpszLongPath 指定的路径的以 null 结尾的短形式。

为此参数传递 NULL ，为 cchBuffer 传递零将始终返回指定 lpszLongPath 所需的缓冲区大小。

[in] cchBuffer

lpszShortPath 指向的缓冲区的大小（以 TCHAR 为单位）。

如果 lpszShortPath 设置为 NULL，则将此参数设置为零。

返回值

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

如果 lpszShortPath 缓冲区太小而无法包含路径，则返回值是缓冲区的大小（以 TCHAR 为单位），用于保存路径和终止 null 字符。

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

注解

lpszLongPath 参数指定的路径不必是完整路径或长路径。短格式可以长于指定路径。

如果返回值大于 cchBuffer 参数中指定的值，则可以使用足够大的缓冲区再次调用函数，以保存路径。有关这种情况的示例以及使用零长度缓冲区进行动态分配，请参阅示例代码部分。

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

如果指定的路径已采用其短格式且不需要转换，则函数只需将指定路径复制到 由 lpszShortPath 参数指定的缓冲区。

可以将 lpszShortPath 参数设置为与 lpszLongPath 参数相同的值;换句话说，可以将短路径的输出缓冲区设置为输入路径字符串的地址。始终确保 cchBuffer 参数准确表示此缓冲区的总大小（以 TCHAR 为单位）。

可以通过调用 GetLongPathName 函数从短名称获取文件的长名称。或者，如果 GetLongPathName 不可用，则可以在路径的每个组件上调用 FindFirstFile 以获取相应的长名称。

可以访问文件或目录，但无权访问该文件或目录的某些父目录。因此， 当 GetShortPathName 无法查询路径组件的父目录以确定该组件的短名称时，GetShortPathName 可能会失败。对于已满足短名称要求的目录组件，可以跳过此检查。有关详细信息，请参阅命名文件、路径和命名空间的短名称与长名称部分。

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

技术	支持
服务器消息块 (SMB) 3.0 协议	是
SMB 3.0 透明故障转移 (TFO)	否
具有横向扩展文件共享的 SMB 3.0 (SO)	否
群集共享卷文件系统 (CSV)	否
弹性文件系统 (ReFS)	是

SMB 3.0 不支持具有连续可用性功能的共享上的短名称。

可复原文件系统 (ReFS) 不支持短名称。如果在磁盘上没有任何短名称的路径上调用 GetShortPathName ，则调用将成功，但将返回长名称路径。对于 NTFS 卷，也可以实现此结果，因为不能保证给定的长名称会出现短名称。

示例

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

以下 C++ 示例演示如何使用动态分配的输出缓冲区。

//...
    long     length = 0;
    TCHAR*   buffer = NULL;

// First obtain the size needed by passing NULL and 0.

    length = GetShortPathName(lpszPath, NULL, 0);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

// Dynamically allocate the correct size 
// (terminating null char was included in length)

    buffer = new TCHAR[length];

// Now simply call again using same long path.

    length = GetShortPathName(lpszPath, buffer, length);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

    _tprintf(TEXT("long name = %s shortname = %s"), lpszPath, buffer);
    
    delete [] buffer;
///...

要求

要求	值
最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	fileapi.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll