IVdsAdvancedDisk::FormatPartition 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 an existing OEM, ESP, or unknown partition.

Syntax

HRESULT FormatPartition(
  [in]  ULONGLONG            ullOffset,
  [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] ullOffset

The partition offset.

[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 volume 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 partition is formatted even while in use; otherwise, the operation fails.

[in] bQuickFormat

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

[in] bEnableCompression

If TRUE, enables compression on the newly formatted file system. Compression is a feature of NTFS and cannot be set for FAT and FAT32 file systems.

[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 partition was formatted successfully.
VDS_E_INVALID_OPERATION 0x80042415L	The disk is removable, or the partition is not of type OEM, ESP, or unknown.
VDS_E_OBJECT_NOT_FOUND 0x80042405L	The partition does not exist.

Remarks

VDS implements this method.

This method formats only OEM, ESP, and unknown partitions. For other partitions, you must instead format the corresponding volume by using the IVdsVolumeMF::Format or IVdsVolumeMF2::FormatEx method. Note that OEM, ESP, and unknown partitions are not exposed as volumes and therefore cannot be formatted with Format or FormatEx.

This method cannot be used to format removable media.

For 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.

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.

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