Функция 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 том E подключен в C:\Mnt\Ddrive\Mnt\Edrive. Также предположим, что у вас есть файл с путем E:\Dir\Subdir\MyFile. При передаче C:\Mnt\Ddrive\Mnt\Edrive\Dir\Subdir\MyFileв GetVolumePathName возвращается путь C:\Mnt\Ddrive\Mnt\Edrive\.

Если относительный каталог или файл передается без квалификатора тома, функция возвращает букву диска загрузочного тома. Буква диска загрузочного тома также возвращается, если указано недопустимое имя файла или каталога без допустимого квалификатора тома. Если задан допустимый описатель тома и том существует, но указано недопустимое имя файла или каталога, функция будет выполнена успешно и будет возвращено это имя тома. Примеры см. в разделе Примеры этой статьи.

Необходимо указать допустимый путь к пространству имен Win32. Если указать путь к пространству имен NT, например или \DosDevices\H:\Device\HardDiskVolume6, функция возвращает букву диска загрузочного тома, а не букву диска этого пути к пространству имен NT.

Дополнительные сведения об именах путей и пространствах имен см. в разделе Именование файлов, путей и пространств имен.

Можно указать как локальные, так и удаленные пути. Если указать локальный путь, GetVolumePathName возвращает полный путь, префикс которого является самым длинным префиксом, представляющим том.

Если указана общая сетевая папка, GetVolumePathName возвращает кратчайшее значение, для которого GetDriveType возвращает DRIVE_REMOTE. Это означает, что путь проверяется как существующий удаленный диск, к которому может получить доступ текущий пользователь.

Существуют некоторые особые случаи, которые не возвращают обратную косую черту в конце. Они возникают, когда длина выходного буфера слишком коротка. Например, если значение lpszFileName имеет значение C: , а значение lpszVolumePathName — 4 символа, возвращается C:\значение ; однако если значение lpszVolumePathName равно 3 символам, возвращается C:значение . Более безопасный, но более медленный способ задать размер возвращаемого буфера — вызвать функцию GetFullPathName , а затем убедиться, что размер буфера по крайней мере совпадает с полным путем, возвращаемым GetFullPathName . Если выходной буфер слишком короткий, функция завершится ошибкой и вернет ошибку.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология Поддерживается
Протокол SMB 3.0 Нет
Прозрачная отработка отказа (TFO) SMB 3.0 Нет
SMB 3.0 с масштабируемыми общими папками (SO) Нет
Файловая система общего тома кластера (CSVFS) Да
Восстанавливаемая файловая система (ReFS) Да

SMB не поддерживает функции управления томами.

Элементы конечного пути

Элементы конечного пути, которые являются недопустимыми, игнорируются. Для удаленных путей весь путь (а не только конечные элементы) считается недопустимым, если выполняется одно из следующих условий:

  • Путь сформирован неправильно.
  • Путь не существует.
  • Текущий пользователь не имеет доступа к пути.

Точки соединения и подключенные папки

Если указанный путь проходит через точку соединения, GetVolumePathName возвращает том, на который ссылается точка соединения. Например, если W:\Adir является точкой соединения, которая указывает на C:\Adir, то GetVolumePathName , вызываемый для W:\Adir\Afile , возвращает 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
Header fileapi.h (включая Windows.h)
Библиотека Kernel32.lib
DLL Kernel32.dll

См. также