CompactVirtualDisk function (virtdisk.h)

Article
02/22/2024

Reduces the size of a virtual hard disk (VHD) backing store file.

Syntax

DWORD CompactVirtualDisk(
  [in]           HANDLE                           VirtualDiskHandle,
  [in]           COMPACT_VIRTUAL_DISK_FLAG        Flags,
  [in, optional] PCOMPACT_VIRTUAL_DISK_PARAMETERS Parameters,
  [in, optional] LPOVERLAPPED                     Overlapped
);

Parameters

[in] VirtualDiskHandle

A handle to the open virtual disk, which must have been opened using the VIRTUAL_DISK_ACCESS_METAOPS flag in the VirtualDiskAccessMask parameter passed to OpenVirtualDisk. For information on how to open a virtual disk, see the OpenVirtualDisk function.

[in] Flags

Must be the COMPACT_VIRTUAL_DISK_FLAG_NONE value (0) of the COMPACT_VIRTUAL_DISK_FLAG enumeration.

[in, optional] Parameters

A optional pointer to a valid COMPACT_VIRTUAL_DISK_PARAMETERS structure that contains compaction parameter data.

[in, optional] Overlapped

An optional pointer to a valid OVERLAPPED structure if asynchronous operation is desired.

Return value

Status of the request.

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error code. For more information, see System Error Codes.

Remarks

Compaction can be run only on a virtual disk that is dynamically expandable or differencing.

There are two different types of compaction.

The first type, file-system-aware compaction, uses the NTFS file system to determine free space. This is done by attaching the VHD as a read-only device by including the VIRTUAL_DISK_ACCESS_METAOPS and VIRTUAL_DISK_ACCESS_ATTACH_RO flags in the VirtualDiskAccessMask parameter passed to OpenVirtualDisk, attaching the VHD by calling AttachVirtualDisk, and while the VHD is attached calling CompactVirtualDisk. Detaching the VHD before compaction is done can cause compaction to return failure before it is done (similar to cancellation of compaction).
The second type, file-system-agnostic compaction, does not involve the file system but only looks for VHD blocks filled entirely with zeros (0). This is done by including the VIRTUAL_DISK_ACCESS_METAOPS flag in the VirtualDiskAccessMask parameter passed to OpenVirtualDisk, and calling CompactVirtualDisk.

File-system-aware compaction is the most efficient compaction type but using first the file-system-aware compaction followed by the file-system-agnostic compaction will produce the smallest VHD.

A compaction operation on a virtual disk can be safely interrupted and re-run later. Re-opening a virtual disk file that has been interrupted may result in the reduction of a virtual disk file's size at the time of opening.

Compaction can be CPU-intensive and/or I/O-intensive, depending on how large the virtual disk is and how many blocks require movement.

The CompactVirtualDisk function runs on the virtual disk in the same security context as the caller.

Requirements

Requirement	Value
Minimum supported client	Windows 7
Minimum supported server	Windows Server 2008 R2
Target Platform	Windows
Header	virtdisk.h
Library	VirtDisk.lib
DLL	VirtDisk.dll