Функция GetVolumeInformationA (fileapi.h)

Статья
04/21/2023

Извлекает сведения о файловой системе и томе, связанном с указанным корневым каталогом.

Чтобы указать дескриптор при получении этих сведений, используйте функцию GetVolumeInformationByHandleW .

Чтобы получить текущее состояние сжатия файла или каталога, используйте FSCTL_GET_COMPRESSION.

Синтаксис

BOOL GetVolumeInformationA(
  [in, optional]  LPCSTR  lpRootPathName,
  [out, optional] LPSTR   lpVolumeNameBuffer,
  [in]            DWORD   nVolumeNameSize,
  [out, optional] LPDWORD lpVolumeSerialNumber,
  [out, optional] LPDWORD lpMaximumComponentLength,
  [out, optional] LPDWORD lpFileSystemFlags,
  [out, optional] LPSTR   lpFileSystemNameBuffer,
  [in]            DWORD   nFileSystemNameSize
);

Параметры

[in, optional] lpRootPathName

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

Если этот параметр имеет значение NULL, используется корень текущего каталога. Требуется обратная косая черта в конце. Например, укажите \\MyServer\MyShare как "\\MyServer\MyShare\" или диск C как "C:\".

[out, optional] lpVolumeNameBuffer

Указатель на буфер, получающий имя указанного тома. Размер буфера определяется параметром nVolumeNameSize .

[in] nVolumeNameSize

Длина буфера имени тома в TCHAR. Максимальный размер буфера — MAX_PATHs+1.

Этот параметр игнорируется, если буфер имени тома не указан.

[out, optional] lpVolumeSerialNumber

Указатель на переменную, которая получает серийный номер тома.

Этот параметр может иметь значение NULL , если серийный номер не требуется.

Эта функция возвращает серийный номер тома, который назначается операционной системой при форматировании жесткого диска. Чтобы программно получить серийный номер жесткого диска, назначенный производителем, используйте инструментарий управления Windows (WMI) Win32_PhysicalMedia свойство SerialNumber.

[out, optional] lpMaximumComponentLength

Указатель на переменную, которая получает максимальную длину (в TCHAR) компонента имени файла, который поддерживает указанная файловая система.

Компонент имени файла — это часть имени файла между обратными косыми чертами.

Значение, хранящееся в переменной , на которую указывает *lpMaximumComponentLength , используется для указания того, что указанная файловая система поддерживает длинные имена. Например, для файловой системы FAT, поддерживающей длинные имена, функция сохраняет значение 255, а не предыдущий индикатор 8.3. Длинные имена также поддерживаются в системах, использующих файловую систему NTFS.

[out, optional] lpFileSystemFlags

Указатель на переменную, получающую флаги, связанные с указанной файловой системой.

Этот параметр может быть одним или несколькими из следующих флагов. Однако FILE_FILE_COMPRESSION и FILE_VOL_IS_COMPRESSED являются взаимоисключающими.

Значение	Значение
FILE_CASE_SENSITIVE_SEARCH 0x00000001	Указанный том поддерживает имена файлов с учетом регистра.
FILE_CASE_PRESERVED_NAMES 0x00000002	Указанный том поддерживает сохраненный регистр имен файлов, когда он помещает имя на диск.
FILE_UNICODE_ON_DISK 0x00000004	Указанный том поддерживает Юникод в именах файлов, как они отображаются на диске.
FILE_PERSISTENT_ACLS 0x00000008	Указанный том сохраняет и применяет списки управления доступом (ACL). Например, файловая система NTFS сохраняет и применяет списки управления доступом, а файловая система FAT — нет.
FILE_FILE_COMPRESSION 0x00000010	Указанный том поддерживает сжатие на основе файлов.
FILE_VOLUME_QUOTAS 0x00000020	Указанный том поддерживает квоты дисков.
FILE_SUPPORTS_SPARSE_FILES 0x00000040	Указанный том поддерживает разреженные файлы.
FILE_SUPPORTS_REPARSE_POINTS 0x00000080	Указанный том поддерживает точки повторного анализа. Refs: ReFS поддерживает точки повторного анализа, но не индексирует их, поэтому FindFirstVolumeMountPoint и FindNextVolumeMountPoint не будут работать должным образом.
FILE_SUPPORTS_REMOTE_STORAGE 0x00000100	Файловая система поддерживает удаленное хранилище.
FILE_RETURNS_CLEANUP_RESULT_INFO 0x00000200	При успешной очистке файловая система возвращает сведения, описывающие дополнительные действия, выполненные во время очистки, например удаление файла. Фильтры файловой системы могут проверять эти сведения в обратном вызове после очистки.
FILE_SUPPORTS_POSIX_UNLINK_RENAME 0x00000400	Файловая система поддерживает операции удаления и переименования в стиле POSIX.
FILE_VOLUME_IS_COMPRESSED 0x00008000	Указанный том является сжатым томом, например томом DoubleSpace.
FILE_SUPPORTS_OBJECT_IDS 0x00010000	Указанный том поддерживает идентификаторы объектов.
FILE_SUPPORTS_ENCRYPTION 0x00020000	Указанный том поддерживает зашифрованную файловую систему (EFS). Дополнительные сведения см. в разделе Шифрование файлов.
FILE_NAMED_STREAMS 0x00040000	Указанный том поддерживает именованные потоки.
FILE_READ_ONLY_VOLUME 0x00080000	Указанный том доступен только для чтения.
FILE_SEQUENTIAL_WRITE_ONCE 0x00100000	Указанный том поддерживает одну последовательную запись.
FILE_SUPPORTS_TRANSACTIONS 0x00200000	Указанный том поддерживает транзакции. Дополнительные сведения см. в разделе Сведения о KTM.
FILE_SUPPORTS_HARD_LINKS 0x00400000	Указанный том поддерживает жесткие связи. Дополнительные сведения см. в разделе Жесткие ссылки и соединения. Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Это значение не поддерживается до Windows Server 2008 R2 и Windows 7.
FILE_SUPPORTS_EXTENDED_ATTRIBUTES 0x00800000	Указанный том поддерживает расширенные атрибуты. Расширенный атрибут — это часть метаданных конкретного приложения, которые приложение может связать с файлом и не является частью данных файла. Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Это значение не поддерживается до Windows Server 2008 R2 и Windows 7.
FILE_SUPPORTS_OPEN_BY_FILE_ID 0x01000000	Файловая система поддерживает открытие по FileID. Дополнительные сведения см. в разделе FILE_ID_BOTH_DIR_INFO. Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Это значение не поддерживается до Windows Server 2008 R2 и Windows 7.
FILE_SUPPORTS_USN_JOURNAL 0x02000000	Указанный том поддерживает журналы с порядком обновления (USN). Дополнительные сведения см. в разделе Изменение записей Журнал. Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Это значение не поддерживается до Windows Server 2008 R2 и Windows 7.
FILE_SUPPORTS_INTEGRITY_STREAMS 0x04000000	Файловая система поддерживает потоки целостности.
FILE_SUPPORTS_BLOCK_REFCOUNTING 0x08000000	Указанный том поддерживает совместное использование логических кластеров между файлами на одном томе. Файловая система перераспределяет операции записи в общие кластеры. Указывает, что FSCTL_DUPLICATE_EXTENTS_TO_FILE является поддерживаемой операцией.
FILE_SUPPORTS_SPARSE_VDL 0x10000000	Файловая система отслеживает, содержит ли каждый кластер файл допустимые данные (из явной записи файлов или автоматических нулей) или недопустимые данные (еще не записаны в или обнулены). Файловые системы, использующие разреженную допустимую длину данных (VDL), не сохраняют допустимую длину данных и не требуют, чтобы допустимые данные были непрерывными в файле.
FILE_DAX_VOLUME 0x20000000	Указанный том является томом с прямым доступом (DAX). Примечание. Этот флаг появился в Windows 10 версии 1607.
FILE_SUPPORTS_GHOSTING 0x40000000	Файловая система поддерживает фантомную функцию.

[out, optional] lpFileSystemNameBuffer

Указатель на буфер, который получает имя файловой системы, например файловой системы FAT или файловой системы NTFS. Размер буфера определяется параметром nFileSystemNameSize .

[in] nFileSystemNameSize

Длина буфера имен файловой системы в TCHAR. Максимальный размер буфера составляет MAX_PATH+1.

Этот параметр игнорируется, если буфер имен файловой системы не указан.

Возвращаемое значение

Если извлекаются все запрошенные сведения, возвращается ненулевое значение.

Если извлекаются не все запрошенные сведения, возвращаемое значение равно нулю. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Когда пользователь пытается получить сведения о дискете, на котором нет дискеты, или компакт-диска без компакт-диска, в системе отображается окно сообщения, в котором пользователь должен вставить гибкий диск или компакт-диск соответственно. Чтобы система не отображала это окно сообщения, вызовите функцию SetErrorMode с SEM_FAILCRITICALERRORS.

Флаг FILE_VOL_IS_COMPRESSED является единственным индикатором сжатия на основе объема. Имя файловой системы не изменяется для указания сжатия, например, этот флаг возвращается для тома DoubleSpace. Если сжатие основано на томе, весь том сжимается или не сжимается.

Флаг FILE_FILE_COMPRESSION указывает, поддерживает ли файловая система сжатие на основе файлов. Если сжатие основано на файлах, отдельные файлы можно сжимать или не сжимать.

Флаги FILE_FILE_COMPRESSION и FILE_VOL_IS_COMPRESSED являются взаимоисключающими. Оба бита не могут быть возвращены набором.

Значение максимальной длины компонента, хранящееся в lpMaximumComponentLength , является единственным показателем того, что том поддерживает имена файловой системы FAT (или другой файловой системы) длиннее обычного. Имя файловой системы не изменяется, чтобы указать на поддержку длинных имен файлов.

Функция GetCompressedFileSize получает сжатый размер файла. Функция GetFileAttributes может определить, сжимается ли отдельный файл.

Поведение символьных ссылок

Если путь указывает на символьную ссылку, функция возвращает сведения о томе для целевого объекта.

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

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

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

Транзакция операций

Если том поддерживает транзакции файловой системы, функция возвращает FILE_SUPPORTS_TRANSACTIONS в lpFileSystemFlags.

Примечание

Заголовок fileapi.h определяет GetVolumeInformation как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	fileapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll