3.4.5.2.29.4 IVdsDiskPartitionMF::FormatPartitionEx (Opnum 6)

  • Article

 The FormatPartitionEx method formats an existing OEM, ESP, or unknown partition. This method is only supported on OEM, ESP, recovery, and unknown partitions.

 HRESULT FormatPartitionEx(
   [in] ULONGLONG ullOffset,
   [in, unique, string] WCHAR* pwszFileSystemTypeName,
   [in] unsigned short usFileSystemRevision,
   [in] unsigned long ulDesiredUnitAllocationSize,
   [in, unique, string] WCHAR* pwszLabel,
   [in] long bForce,
   [in] long bQuickFormat,
   [in] long bEnableCompression,
   [out] IVdsAsync** ppAsync
 );

ullOffset: The byte offset of the partition from the beginning of the disk. This MUST be the offset at the start of a partition.

pwszFileSystemTypeName: A null-terminated Unicode string that contains the name of the file system with which to format the partition.

usFileSystemRevision: A 16-bit, binary-coded decimal number that indicates the revision of the file system, if any. The first two (most significant) digits (8-bits) indicate the major revision while the last two (least significant) digits (8-bits) indicate the minor revision (for example, 0x0250 represents revision 2.50).

ulDesiredUnitAllocationSize: The size, in bytes, of the allocation unit for the file system. The value MUST be a power of 2. If the value is 0, a default allocation unit determined by the file system type is used. The allocation unit range is file system-dependent.

pwszLabel: The null-terminated Unicode string to assign to the new file system. The maximum label size is file system-dependent.

bForce: A Boolean that determines whether a file system format is forced, even if the partition is in use.

bQuickFormat: A Boolean that determines whether a file system is quick formatted. A quick format does not verify each sector on the volume.

bEnableCompression: A Boolean that determines whether a file system is created with compression enabled.<108>

ppAsync: A pointer to an IVdsAsync interface that, if the operation is successfully completed, receives the IVdsAsync interface to monitor and control this operation. Callers MUST release the interface when they are done with it.

Return Values: The method MUST return zero or a non-error HRESULT (as specified in [MS-ERREF]) to indicate success, or return an implementation-specific nonzero error code to indicate failure. For the HRESULT values predefined by the Virtual Disk Service Remote Protocol, see section 2.2.3.

Note This method is not valid on CD/DVD or super floppy devices. These devices do not support partition table.

ERROR_SUCCESS (0x00000000)

When the server receives this message, it MUST validate the following parameter:

  • Verify that ppAsync is not NULL.

  • Verify that the partition at offset ullOffset is an OEM, ESP, recovery, or unknown partition.

  • Create a new async object implementing the IVdsAsync interface with an output type of VDS_ASYNCOUT_FORMAT and set the pointer ppAsync references to the interface.

  • Return an HRESULT indicating failure or success. Any errors encountered up through this point in processing the FormatPartitionEx operation are returned in this HRESULT.

The server MUST perform the following. Errors generated in this sequence of steps are returned in the pHrResult parameter to the IVdsAsync::Wait or IVdsAsyncQueryStatus methods.

  • If the operating system is unable to format the device using the file system type that is specified using the type parameter, then this method MUST return VDS_E_INCOMPATIBLE_FILE_SYSTEM.

  • If the target device\media is write-protected, then this method MUST return VDS_E_MEDIA_WRITE_PROTECTED.

  • If the pwszLabel parameter is incompatible with the file system type specified using the type parameter, then the server MUST return VDS_E_BAD_LABEL.

  • If the specified file system type has a minimum volume size requirement, and that requirement is not met, then the server MUST return VDS_E_VOLUME_TOO_SMALL.

  • If the specified file system type has a maximum volume size requirement, and that requirement is not met, then the server MUST return VDS_E_VOLUME_TOO_BIG.

  • If the specified file system type has a minimum or maximum cluster size requirement, and that requirement is not met, then the server MUST return VDS_E_CLUSTER_SIZE_TOO_SMALL or VDS_E_CLUSTER_SIZE_TOO_BIG, respectively.

  • If the specified file system type has a maximum cluster count requirement, and that requirement is not met, then the server MUST return VDS_E_CLUSTER_COUNT_BEYOND_32BITS.

The server MUST update the percentage completed value periodically during the following sequence, and send progress notifications to all clients. How often the percentage completed is updated, and at what point in the sequence, is implementation specific. To send progress notifications to the clients:

  • For each callback object registered in the list of callback objects, call the callback object's IVdsAdviseSink::OnNotify (Opnum 3) method with a VDS_NOTIFICATION structure with the following attributes:

    • objectType member is VDS_NTT_FILE_SYSTEM.

    • FileSystem member is a VDS_FILE_SYSTEM_NOTIFICATION with the following attributes:

      • ulEvent is VDS_NF_FILE_SYSTEM_FORMAT_PROGRESS.

      • volumeId is set to GUID_NULL.

      • dwPercentCompleted is the percentage completed value.

The server MUST then perform the following in sequence:

  • Format the partition following the parameters specified to the method.

  • If TRUE is specified for bEnableCompression and the file system being formatted supports compression, compress the file system after formatting is complete.<109>

  • Set the return code in the async object to an HRESULT indicating failure or success.

    • If the server was required to compress the file system after formatting but could not, the return code MUST be set to VDS_S_VOLUME_COMPRESS_FAILED (HRESULT of 0x00042443).

  • If the task completed successfully, set the percentage completed value in the async object to 100.

  • Set the signal state in the async object to TRUE.