Share via

3.2.4.4.1.4 IVolumeClient::CreatePartitionAssignAndFormat (Opnum 6)

  • Article

The CreatePartitionAssignAndFormat method creates a partition, formats it as a file system, and assigns it a drive letter.

 HRESULT CreatePartitionAssignAndFormat(
   [in] REGION_SPEC partitionSpec,
   [in] wchar_t letter,
   [in] hyper letterLastKnownState,
   [in] FILE_SYSTEM_INFO fsSpec,
   [in] boolean quickFormat,
   [out] TASK_INFO* tinfo
 );

partitionSpec: A REGION_SPEC structure that defines the type and length of the partition to create.

letter: Drive letter to assign to the new volume, specified as a single, case-insensitive Unicode character.

letterLastKnownState: Drive letter's last known modification sequence number.

fsSpec: A FILE_SYSTEM_INFO structure that defines the file system to create.

quickFormat: Boolean value that determines whether the server will fully format or quickly format the file system.

Value

Meaning

FALSE

0

File system will be fully formatted. Full format requires verifying the accessibility of all sectors on the volume.

TRUE

1

File system will be quickly formatted.

tinfo: Pointer to a TASK_INFO structure that the client can use to track the request's progress.

Return Values: The method MUST return 0 or a nonerror HRESULT on success, or an implementation-specific nonzero error code on failure (as specified in [MS-ERREF] section 2.1; see also section 2.2.1 for HRESULT values predefined by the Disk Management Remote Protocol).

Upon receiving this message, the server MUST validate parameters:

  1. Verify that the disk specified by partitionSpec.diskId is in the list of storage objects.

  2. Verify that the disk region specified by partitionSpec.regionId is in the list of storage objects, and check if partitionSpec.LastKnownState matches the LastKnownState field of the object.

  3. Verify that the partitionSpec.regionId specified matches the regionId field of one of the regions in the disk specified by partitionSpec.diskId.

  4. Verify that the drive letter object specified by letter is in the list of storage objects, and check whether letterLastKnowState matches the LastKnownState field of the object.<25>

  5. Verify that tinfo is not NULL.

If parameter validation fails, the server MUST fail the operation immediately, returning an appropriate error as its response to the client.

Otherwise, the server MUST process the message as follows:

  1. Create a partition on the free disk region specified by partitionSpec.regionId of the disk specified by partitionSpec.diskId. The starting offset of the partition is specified by partitionSpec.start and the length of the partition is specified by partitionSpec.length. The type of the partition to be created is specified by the partitionType.regionType partition.

  2. Wait for the partition creation to either succeed or fail.

  3. If successful, assign the drive letter specified by letter to the partition.

  4. Wait for the drive letter assignment to either succeed or fail.

  5. If successful, start formatting the partition with the file system specified by fsSpec, as specified by the quickFormat parameter.

  6. Fill in the tinfo output parameter. This is an asynchronous task.

    • The tinfo.storageId field MUST be set to the identifier of the disk region object corresponding to the new partition.<26>

      TASK_INFO member

      Required for this operation

      TASK_INFO::id

      Required.

      TASK_INFO::storageId

      Required.

      TASK_INFO::createTime

      Not required.<27>

      TASK_INFO::clientID

      Not required.<28>

      TASK_INFO::percentComplete

      Required for any task that returns REQ_IN_PROGRESS.

      TASK_INFO::status

      Required.

      TASK_INFO::type

      Required if PercentageComplete is being used.

      TASK_INFO::error

      Required.

      TASK_INFO::tflag

      Not required.<29>

  7. Return a response to the client containing tinfo and the status of the operation.

Note The server MAY decide not to wait for the formatting to complete before returning the response to the client.<30> This task is asynchronous and all rules for handling asynchronous tasks apply here.

If the creation of the partition is successful, the server MUST make the following changes to the list of storage objects before returning the response:

  1. Modify the disk object where the new partition resides to account for the change in region allocation.

  2. Create a new disk region object corresponding to the new partition.

  3. Modify or delete the free disk region object where the partition was created to account for the allocation of a new partition in that region.

If the drive letter assignment is successful, the server MUST make the following change to the list of storage objects before returning the response:

  • Modify the drive letter object to mark it as in use by the new partition.

If the format operation has been successfully started, the server MUST make the following change to the list of storage objects before returning the response:

  • Create a new file system object.

When the formatting is finished, the server MUST make the following change to the list of storage objects.

  • Modify the disk region object that corresponds to the partition to account for the change of status.