IVdsVolumeMF2::FormatEx method (vds.h)
[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 volume on a partition.
Syntax
HRESULT FormatEx(
[in] LPWSTR pwszFileSystemTypeName,
[in] USHORT usFileSystemRevision,
[in] ULONG ulDesiredUnitAllocationSize,
[in] LPWSTR pwszLabel,
[in] BOOL bForce,
[in] BOOL bQuickFormat,
[in] BOOL bEnableCompression,
[out] IVdsAsync **ppAsync
);
Parameters
[in] pwszFileSystemTypeName
Null-terminated Unicode string containing the name of the file system with which to format the volume. This parameter can be NULL or the name of a Windows file system. The following file systems are supported: "NTFS", "FAT", "FAT32", "UDF", and "EXFAT". If this parameter is NULL, the default file system is used. For more information, see VDS_FILE_SYSTEM_FORMAT_SUPPORT_FLAG.
[in] usFileSystemRevision
The revision of the file system, if any. This member is expressed as a 16-bit binary-coded decimal number, where a decimal point is implied between the second and third digits. For example, a value of 0x0250 indicates revision 2.50.
[in] ulDesiredUnitAllocationSize
The size of the allocation unit for the file system, in bytes. The value must be a power of 2. If the value is 0, a default allocation unit determined by the file system type will be used. The allocation unit range is file system dependent.
[in] pwszLabel
Null-terminated Unicode string to assign to the new file system. The maximum label size is file system dependent.
[in] bForce
Boolean that determines whether a file system format is forced, regardless of whether the partition is in use.
[in] bQuickFormat
Boolean that determines whether a file system volume is quick-formatted. A quick format does not verify each sector on the volume.
[in] bEnableCompression
Boolean that determines whether the file system volume will be created with compression enabled.
[out] ppAsync
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 are done with it.
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 |
---|---|
|
The file system was formatted successfully. |
|
The operation is denied if the caller tries to format the system, boot, crashdump, hibernation, or pagefile volume. |
|
The volume has failed. |
|
The pack containing the volume is not accessible. All volumes in an offline pack are inaccessible. |
|
The default file system could not be determined. |
In addition, the IVdsAsync interface can return the following related warnings and error codes:
Return code/value | Description |
---|---|
|
The file system is incompatible. |
|
The media is incompatible. |
|
Access is denied. |
|
The media is write-protected. |
|
The label is not valid. |
|
The volume cannot be quick-formatted. |
|
An I/O error occurred during format. |
|
The volume size is too small to format. |
|
The volume size is too large to format. |
|
The cluster size is too small to allow formatting. |
|
The cluster size is too large to allow formatting. |
|
The number of clusters is too large to be represented as a 32-bit integer. |
|
The file system is formatted but not compressed. |
|
BitLocker encryption could not be disabled for the volume. |
Remarks
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 2008 [desktop apps only] |
Target Platform | Windows |
Header | vds.h |
Library | Uuid.lib |