GetVolumeInformationByHandleW function (fileapi.h)

Retrieves information about the file system and volume associated with the specified file.

To retrieve the current compression state of a file or directory, use FSCTL_GET_COMPRESSION.

Syntax

BOOL GetVolumeInformationByHandleW(
  [in]            HANDLE  hFile,
  [out, optional] LPWSTR  lpVolumeNameBuffer,
  [in]            DWORD   nVolumeNameSize,
  [out, optional] LPDWORD lpVolumeSerialNumber,
  [out, optional] LPDWORD lpMaximumComponentLength,
  [out, optional] LPDWORD lpFileSystemFlags,
  [out, optional] LPWSTR  lpFileSystemNameBuffer,
  [in]            DWORD   nFileSystemNameSize
);

Parameters

[in] hFile

A handle to the file.

[out, optional] lpVolumeNameBuffer

A pointer to a buffer that receives the name of a specified volume. The maximum buffer size is MAX_PATH+1.

[in] nVolumeNameSize

The length of a volume name buffer, in WCHARs. The maximum buffer size is MAX_PATH+1.

This parameter is ignored if the volume name buffer is not supplied.

[out, optional] lpVolumeSerialNumber

A pointer to a variable that receives the volume serial number.

This parameter can be NULL if the serial number is not required.

This function returns the volume serial number that the operating system assigns when a hard disk is formatted. To programmatically obtain the hard disk's serial number that the manufacturer assigns, use the Windows Management Instrumentation (WMI) Win32_PhysicalMedia property SerialNumber.

[out, optional] lpMaximumComponentLength

A pointer to a variable that receives the maximum length, in WCHARs, of a file name component that a specified file system supports.

A file name component is the portion of a file name between backslashes.

The value that is stored in the variable that *lpMaximumComponentLength points to is used to indicate that a specified file system supports long names. For example, for a FAT file system that supports long names, the function stores the value 255, rather than the previous 8.3 indicator. Long names can also be supported on systems that use the NTFS file system.

[out, optional] lpFileSystemFlags

A pointer to a variable that receives flags associated with the specified file system.

This parameter can be one or more of the following flags. However, FILE_FILE_COMPRESSION and FILE_VOL_IS_COMPRESSED are mutually exclusive.

Value Meaning
FILE_CASE_SENSITIVE_SEARCH
0x00000001
The specified volume supports case-sensitive file names.
FILE_CASE_PRESERVED_NAMES
0x00000002
The specified volume supports preserved case of file names when it places a name on disk.
FILE_UNICODE_ON_DISK
0x00000004
The specified volume supports Unicode in file names as they appear on disk.
FILE_PERSISTENT_ACLS
0x00000008
The specified volume preserves and enforces access control lists (ACL). For example, the NTFS file system preserves and enforces ACLs, and the FAT file system does not.
FILE_FILE_COMPRESSION
0x00000010
The specified volume supports file-based compression.
FILE_VOLUME_QUOTAS
0x00000020
The specified volume supports disk quotas.
FILE_SUPPORTS_SPARSE_FILES
0x00000040
The specified volume supports sparse files.
FILE_SUPPORTS_REPARSE_POINTS
0x00000080
The specified volume supports re-parse points.
FILE_VOLUME_IS_COMPRESSED
0x00008000
The specified volume is a compressed volume, for example, a DoubleSpace volume.
FILE_SUPPORTS_OBJECT_IDS
0x00010000
The specified volume supports object identifiers.
FILE_SUPPORTS_ENCRYPTION
0x00020000
The specified volume supports the Encrypted File System (EFS). For more information, see File Encryption.
FILE_NAMED_STREAMS
0x00040000
The specified volume supports named streams.
FILE_READ_ONLY_VOLUME
0x00080000
The specified volume is read-only.
FILE_SEQUENTIAL_WRITE_ONCE
0x00100000
The specified volume supports a single sequential write.
FILE_SUPPORTS_TRANSACTIONS
0x00200000
The specified volume supports transactions. For more information, see About KTM.
FILE_SUPPORTS_HARD_LINKS
0x00400000
The specified volume supports hard links. For more information, see Hard Links and Junctions.

Windows Vista and Windows Server 2008: This value is not supported.

FILE_SUPPORTS_EXTENDED_ATTRIBUTES
0x00800000
The specified volume supports extended attributes. An extended attribute is a piece of application-specific metadata that an application can associate with a file and is not part of the file's data.

Windows Vista and Windows Server 2008: This value is not supported.

FILE_SUPPORTS_OPEN_BY_FILE_ID
0x01000000
The file system supports open by FileID. For more information, see FILE_ID_BOTH_DIR_INFO.

Windows Vista and Windows Server 2008: This value is not supported.

FILE_SUPPORTS_USN_JOURNAL
0x02000000
The specified volume supports update sequence number (USN) journals. For more information, see Change Journal Records.

Windows Vista and Windows Server 2008:  This value is not supported.

FILE_SUPPORTS_BLOCK_REFCOUNTING
0x08000000
The specified volume supports sharing logical clusters between files on the same volume. The file system reallocates on writes to shared clusters. Indicates that FSCTL_DUPLICATE_EXTENTS_TO_FILE is a supported operation.

[out, optional] lpFileSystemNameBuffer

A pointer to a buffer that receives the name of the file system, for example, the FAT file system or the NTFS file system. The buffer size is specified by the nFileSystemNameSize parameter.

[in] nFileSystemNameSize

The length of the file system name buffer, in WCHARs. The maximum buffer size is MAX_PATH+1.

This parameter is ignored if the file system name buffer is not supplied.

Return value

If all the requested information is retrieved, the return value is nonzero.

If not all the requested information is retrieved, the return value is zero. To get extended error information, call GetLastError.

Remarks

In Windows 8 and Windows Server 2012, this function is supported by the following technologies.

Technology Supported
Server Message Block (SMB) 3.0 protocol No
SMB 3.0 Transparent Failover (TFO) No
SMB 3.0 with Scale-out File Shares (SO) No
Cluster Shared Volume File System (CsvFS) Yes
Resilient File System (ReFS) Yes

SMB does not support volume management functions.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header fileapi.h (include Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

See also

About KTM

File Encryption

GetCompressedFileSize

GetFileAttributes

GetVolumeInformation

SetErrorMode

SetVolumeLabel

Volume Management Functions