IVdsVolumeMF::Format method (vds.h)

Article
02/09/2023

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

Formats a file system on the current volume.

Syntax

HRESULT Format(
  [in]  VDS_FILE_SYSTEM_TYPE type,
  [in]  LPWSTR               pwszLabel,
  [in]  DWORD                dwUnitAllocationSize,
  [in]  BOOL                 bForce,
  [in]  BOOL                 bQuickFormat,
  [in]  BOOL                 bEnableCompression,
  [out] IVdsAsync            **ppAsync
);

Parameters

[in] type

A VDS_FILE_SYSTEM_TYPE enumeration value that specifies the file system to be used. Must be one of the following: VDS_FST_NTFS, VDS_FST_FAT, VDS_FST_FAT32, or VDS_FST_UDF.

[in] pwszLabel

A string representing the file system label.

[in] dwUnitAllocationSize

The size of the allocation unit for the file system in bytes, which is usually between 512 and 65536.

[in] bForce

If TRUE, the file system is formatted unconditionally even while in use; otherwise, the operation fails.

[in] bQuickFormat

If TRUE, VDS performs a quick format (it does not verify each sector on the volume).

[in] bEnableCompression

If TRUE, compression is enabled on the newly formatted file system. Compression is a feature of NTFS, and is ignored for FAT and FAT32.

[out] ppAsync

The address of an IVdsAsync interface pointer, which VDS initializes on return. Callers must release the interface. Use this pointer to cancel, wait for, or query the status of the operation.

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/value	Description
S_OK	The file system was formatted successfully.
VDS_E_OPERATION_DENIED 0x8004240AL	The operation is denied if the caller tries to format the system, boot, crashdump, hibernation, or pagefile volumes.
VDS_E_OBJECT_STATUS_FAILED 0x80042431L	The volume has failed.
VDS_E_PACK_OFFLINE 0x80042444L	The pack containing the volume is not accessible. All volumes in an offline pack are inaccessible.

In addition, the IVdsAsync interface can return the following related warnings and error codes.

Return code/value	Description
VDS_S_VOLUME_COMPRESS_FAILED 0x00042443L	The file system is formatted but not compressed.
VDS_E_INCOMPATIBLE_FILE_SYSTEM 0x80042425L	The file system is incompatible.
VDS_E_INCOMPATIBLE_MEDIA 0x80042426L	The media is incompatible.
VDS_E_ACCESS_DENIED 0x80042427L	Access is denied.
VDS_E_MEDIA_WRITE_PROTECTED 0x80042428L	The media is write-protected.
VDS_E_BAD_LABEL 0x80042429L	The label is not valid.
VDS_E_CANT_QUICK_FORMAT 0x8004242AL	The volume cannot be quick formatted.
VDS_E_IO_ERROR 0x8004242BL	An IO error occurred during format.
VDS_E_VOLUME_TOO_SMALL 0x8004242CL	The volume size is too small to format.
VDS_E_VOLUME_TOO_BIG 0x8004242DL	The volume size is too large to format.
VDS_E_CLUSTER_SIZE_TOO_SMALL 0x8004242EL	The cluster size is too small to allow formatting.
VDS_E_CLUSTER_SIZE_TOO_BIG 0x8004242FL	The cluster size is too large to allow formatting.
VDS_E_CLUSTER_COUNT_BEYOND_32BITS 0x80042430L	The number of clusters is too large to represent as a 32-bit integer.
VDS_E_INVALID_FS_TYPE 0x80042561L	The value of the type parameter was not VDS_FST_NTFS, VDS_FST_FAT, VDS_FST_FAT32, or VDS_FST_UDF.
VDS_E_CANT_INVALIDATE_FVE 0x80042592L	BitLocker encryption could not be disabled for the volume.

Remarks

To create a boot volume on a dynamic disk, you must call IVdsVolume::SetFlags to set the VDS_VF_INSTALLABLE flag before calling Format to format the volume.

If an OEM partition is formatted as FAT or FAT32, the partition type does not change. If it is formatted with NTFS, the partition type changes to PARTITION_IFS (0x07). For information about partition types, see CREATE_PARTITION_PARAMETERS.

If this method is called for a volume that is protected by BitLocker full-volume encryption, BitLocker encryption is disabled for the volume until the user re-enables it.

For more information about file system limits such as minimum and maximum allocation unit size (also called cluster size), see NTFS Technical Reference and FAT Technical Reference.

Requirements

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