Edit

Share via

IVdsOpenVDisk::Compact method (vds.h)

  • Article

[Beginning with Windows 8 and Windows Server 2012, the Virtual Disk Service COM interface is superseded by the Windows Storage Management API.]

Compacts the virtual disk to reduce the physical size of the backing file.

Syntax

HRESULT Compact(
  [in]  COMPACT_VIRTUAL_DISK_FLAG Flags,
  [in]  ULONG                     Reserved,
  [out] IVdsAsync                 **ppAsync
);

Parameters

[in] Flags

A COMPACT_VIRTUAL_DISK_FLAG enumeration value that specifies how the virtual disk is to be compacted. Must be set to COMPACT_VIRTUAL_DISK_FLAG_NONE.

[in] Reserved

This parameter is reserved for system use.

[out] ppAsync

A pointer to an IVdsAsync interface that upon successful completion receives the IVdsAsync interface to monitor and control this operation. Callers must release the interface received when they have finished with it. If the IVdsAsync::Wait method is called on the interface and a success HRESULT value is returned, the interfaces returned in the VDS_ASYNC_OUTPUT structure must be released by calling the IUnknown::Release method on each interface pointer. However, if Wait returns a failure HRESULT value, or if the pHrResult parameter of Wait receives a failure HRESULT value, the interface pointers in the VDS_ASYNC_OUTPUT structure are NULL and do not need to be released. You can test for success or failure HRESULT values by using the SUCCEEDED and FAILED macros defined in Winerror.h.

Return value

This method can return standard HRESULT values, such as E_INVALIDARG or E_OUTOFMEMORY, and VDS-specific return values. It can also return converted system error codes using the HRESULT_FROM_WIN32 macro. Errors can originate from VDS itself or from the underlying VDS provider that is being used. Possible return values include the following.

Return code Description
S_OK
 The method completed successfully.

Remarks

A virtual disk can be compacted only if it is in one of the following states:

  • Detached (offline mode)
  • Attached and opened with read-only access (online mode)
If it is in any other state, the compact operation fails.

The virtual disk must be an expandable (also called dynamic) or differencing virtual disk.

The operation can be safely interrupted and re-run later. If the operation is interrupted and the backing file is reopened, the file's size may be reduced when the file is opened.

The operation can be CPU-intensive or I/O-intensive, or both, depending on how large the virtual disk is and how many unused blocks require manipulation.

This method reduces the size of the virtual disk's backing store file by reclaiming unused space. If this method is called for a virtual disk that is detached, it can only reclaim space in the file that was never used to write data. If it is called for a virtual disk that is attached and opened with read-only access, it is able to reclaim space that was once used, but was later freed. Calling this method for a virtual disk that is attached and opened with read-only access reclaims the maximum amount of free space in the backing store file.

Requirements

Requirement Value
Minimum supported client Windows 7 [desktop apps only]
Minimum supported server Windows Server 2008 R2 [desktop apps only]
Target Platform Windows
Header vds.h
Library Uuid.lib

See also

IVdsOpenVDisk