CompactVirtualDisk function

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_opt_ PCOMPACT_VIRTUAL_DISK_PARAMETERS Parameters,
  _In_opt_ LPOVERLAPPED                     Overlapped
);

Parameters

VirtualDiskHandle [in]

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.

Flags [in]

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

Parameters [in, optional]

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

Overlapped [in, optional]

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

Minimum supported client

Windows 7

Minimum supported server

Windows Server 2008 R2

Header

VirtDisk.h (include Windows.h)

Library

VirtDisk.lib

DLL

VirtDisk.dll

See also

About VHD
VHD Reference

 

 

Show: