getVolumePathNameW 函数 (fileapi.h)

  • 项目

检索装载指定路径的卷装入点。

语法

BOOL GetVolumePathNameW(
  [in]  LPCWSTR lpszFileName,
  [out] LPWSTR  lpszVolumePathName,
  [in]  DWORD   cchBufferLength
);

参数

[in] lpszFileName

指向输入路径字符串的指针。 绝对和相对文件和目录名称（例如“..”）在此路径中都是可接受的。

如果不指定卷限定符的相对目录或文件名， GetVolumePathName 将返回启动卷的驱动器号。

如果此参数是空字符串“”，则函数失败，但最后一个错误设置为 ERROR_SUCCESS。

[out] lpszVolumePathName

指向接收输入路径的卷装入点的字符串的指针。

[in] cchBufferLength

输出缓冲区的长度，以 TCHAR 为单位。

返回值

如果该函数成功，则返回值为非零值。

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

注解

如果传递指定路径， GetVolumePathName 将返回卷装入点的路径，这意味着它将返回指定路径终结点所在的卷的根目录。

例如，假设已在 中装载卷 D，在 C:\Mnt\Ddrive 上装载了 C:\Mnt\Ddrive\Mnt\Edrive卷 E。 此外，假设你有一个路径 E:\Dir\Subdir\MyFile为 的文件。 如果传递给 C:\Mnt\Ddrive\Mnt\Edrive\Dir\Subdir\MyFileGetVolumePathName，它将返回路径 C:\Mnt\Ddrive\Mnt\Edrive\。

如果在不使用卷限定符的情况下传递了相对目录或文件，则函数将返回启动卷的驱动器号。 如果在未指定有效的卷限定符的情况下指定无效的文件或目录名称，则也会返回启动卷的驱动器号。 如果提供了有效的卷说明符，并且卷存在，但指定了无效的文件或目录名称，则该函数将成功，并且将返回该卷名称。 有关示例，请参阅本主题的示例部分。

必须指定有效的 Win32 命名空间路径。 如果指定 NT 命名空间路径（例如 \DosDevices\H: 或 \Device\HardDiskVolume6），函数将返回启动卷的驱动器号，而不是该 NT 命名空间路径的驱动器号。

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

可以指定本地路径和远程路径。 如果指定本地路径， GetVolumePathName 将返回一个完整路径，其前缀是表示卷的最长前缀。

如果指定了网络共享， GetVolumePathName 将返回 GetDriveTypeDRIVE_REMOTE的最短路径，这意味着该路径将验证为存在的远程驱动器，当前用户可以访问该路径。

某些特殊情况不返回尾随反斜杠。 当输出缓冲区长度太短一个字符时，会发生这些情况。 例如，如果 lpszFileName 为 C: ， lpszVolumePathName 的长度为 4 个字符，则返回的值为 C:\;但是，如果 lpszVolumePathName 的长度为 3 个字符，则返回 C:的值为 。 设置返回缓冲区大小的一种更安全但较慢的方法是调用 GetFullPathName 函数，然后确保缓冲区大小至少与 GetFullPathName 返回的完整路径大小相同。 如果输出缓冲区的多个字符太短，函数将失败并返回错误。

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

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

SMB 不支持卷管理功能。

尾随路径元素

忽略无效的尾随路径元素。 对于远程路径，如果满足以下条件之一，则整个路径 (而不仅仅是尾随元素) 被视为无效：

  • 路径格式不正确。
  • 路径不存在。
  • 当前用户无权访问路径。

交汇点和装载的文件夹

如果指定路径遍历交汇点， GetVolumePathName 将返回该交汇点所引用的卷。 例如，如果 W:\Adir 是指向 C:\Adir的交点，则在 上W:\Adir\Afile调用的 GetVolumePathName 将C:\返回 。 如果指定路径遍历多个交汇点，则遵循整个链， GetVolumePathName 返回链中最后一个交界点所引用的卷。

如果指定了已装载文件夹或交汇点的远程路径，则会将路径分析为远程路径，并忽略装载的文件夹或交汇点。 例如，如果 C:\Dir_C 链接到 D:\Dir_D 远程计算机上并 C: 映射到 X: ，则调用 GetVolumePathName 并在远程计算机上指定 X:\Dir_C 将 X:\返回 。

示例

对于以下一组示例，U： 映射到远程计算机 \\_YourComputer_\C$，而 Q 是本地驱动器。

指定的路径 函数返回
\\_YourComputer_\C$\Windows \\_YourComputer_\C$\
\\?\UNC\_YourComputer_\C$\Windows \\?\UNC\_YourComputer_\C$\
Q:\Windows Q:\
\\?\Q:\Windows \\?\Q:\
\\.\Q:\Windows \\.\Q:\
\\?\UNC\W:\Windows FALSE ，错误 123，因为指定的远程路径无效;W$ 共享不存在或未授予用户访问权限。
C:\COM2 存在的 () \\.\COM2\
C:\COM3 (不存在) FALSE ，错误 123，因为指定了不存在的 COM 设备。

对于以下一组示例，路径包含无效的尾随路径元素。

指定的路径 函数返回
G:\invalid (无效路径) G:\
\\.\I:\aaa\invalid (无效路径) \\.\I:\
\\_YourComputer_\C$\invalid (无效的尾随路径元素) \\_YourComputer_\C$\

要求

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

另请参阅