Windows File System API: Volumes Reference

Volumes

This section provides information on the Windows API functions and structures related to file system volumes. Volumes represent storage devices formatted with a file system, such as hard drives, solid-state drives, and removable media.

Key Concepts

Volume Identification: How to identify and distinguish between different volumes.
Volume Properties: Retrieving information such as label, serial number, file system type, and total/free space.
Volume Management: Functions for mounting, dismounting, and manipulating volumes.

Core API Functions

`GetDriveType`

Determines the type of a disk drive (e.g., removable disk, fixed disk, CD-ROM).

UINT GetDriveType(
        LPCTSTR lpRootPathName
    );

lpRootPathName: A pointer to a null-terminated string that specifies the root directory of a drive (e.g., "C:\\").
Return Value: An integer representing the drive type, or 0 if the drive type cannot be determined.

Note: This function is fundamental for understanding the nature of a storage device before performing other operations.

`GetLogicalDrives`

Retrieves a bitmask representing the available disk drives in the system.

DWORD GetLogicalDrives(
        void
    );

Return Value: A bitmask where each bit corresponds to a drive letter. For example, bit 0 is drive A:, bit 1 is drive B:, and so on.

`GetVolumeInformation`

Retrieves information about a file system and a file system volume.

BOOL GetVolumeInformation(
        LPCTSTR lpRootPathName,
        LPTSTR  lpVolumeNameBuffer,
        DWORD   nVolumeNameSize,
        LPDWORD lpVolumeSerialNumber,
        LPDWORD lpMaximumComponentLength,
        LPDWORD lpFileSystemFlags,
        LPTSTR  lpFileSystemNameBuffer,
        DWORD   nFileSystemNameSize
    );

lpRootPathName: The root directory of the volume.
lpVolumeNameBuffer: A buffer to receive the volume's name.
nVolumeNameSize: The size of the volume name buffer.
lpVolumeSerialNumber: A pointer to a variable that receives the volume's serial number.
lpMaximumComponentLength: A pointer to a variable that receives the maximum length of a file name component.
lpFileSystemFlags: A pointer to a variable that receives flags about the file system.
lpFileSystemNameBuffer: A buffer to receive the name of the file system (e.g., "NTFS", "FAT32").
nFileSystemNameSize: The size of the file system name buffer.
Return Value: TRUE if the function succeeds, FALSE otherwise.

Important: Ensure that the buffer sizes provided for volume name and file system name are adequate to prevent buffer overflows.

`GetDiskFreeSpaceEx`

Retrieves information about the amount of free space on a specified disk.

BOOL GetDiskFreeSpaceEx(
        LPCTSTR       lpDirectoryName,
        ULARGE_INTEGER* lpFreeBytesAvailableToCaller,
        ULARGE_INTEGER* lpTotalNumberOfBytes,
        ULARGE_INTEGER* lpTotalNumberOfFreeBytes
    );

lpDirectoryName: A pointer to a string that specifies the directory on the disk for which the disk space information is to be retrieved.
lpFreeBytesAvailableToCaller: A pointer to a ULARGE_INTEGER structure that receives the number of free bytes on the disk that are available to the process.
lpTotalNumberOfBytes: A pointer to a ULARGE_INTEGER structure that receives the total number of bytes on the disk.
lpTotalNumberOfFreeBytes: A pointer to a ULARGE_INTEGER structure that receives the total number of free bytes on the disk.
Return Value: TRUE if the function succeeds, FALSE otherwise.

Structures

`ULARGE_INTEGER`

A union that supports the manipulation of unsigned 64-bit integers. Used extensively with disk space functions.

typedef union _ULARGE_INTEGER {
        struct {
            DWORD LowPart;
            DWORD HighPart;
        } DUMMYUNIONNAME;
        ULONGLONG QuadPart;
    } ULARGE_INTEGER;

Windows API Reference