3.2.4.4.1.27 IVolumeClient::CreateVolumeAssignAndFormat (Opnum 31)

  • Article

The CreateVolumeAssignAndFormat method creates a dynamic volume on the specified list of disks, assigns a drive letter to it, and formats it with a file system.

 HRESULT CreateVolumeAssignAndFormat(
   [in] VOLUME_SPEC volumeSpec,
   [in] unsigned long diskCount,
   [in, size_is(diskCount)] DISK_SPEC* diskList,
   [in] wchar_t letter,
   [in] hyper letterLastKnownState,
   [in] FILE_SYSTEM_INFO fsSpec,
   [in] boolean quickFormat,
   [out] TASK_INFO* tinfo
 );

volumeSpec: A VOLUME_SPEC structure that defines the volume to create.

diskCount: Number of elements passed in diskList.

diskList: Array of DISK_SPEC structures that specifies the disks to be used by the volume. Memory for the array is allocated and freed by the client.

letter: Drive letter to assign to the new volume. If no drive letter is needed for the volume, the value of this field MUST be a 2-byte null character or the Unicode SPACE 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 indicates 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]; 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 diskCount is not 0 and diskList is not NULL.

  2. For each DISK_SPEC structure in diskList, verify that the disk specified by diskId is in the list of storage objects; and check whether lastKnownState matches the LastKnownState field of the object.

  3. Verify that the drive letter object, if specified by letter, is in the list of storage objects, and check whether letterLastKnownState matches the LastKnownState field of the object. <99>

  4. 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. Attempt to create the dynamic volume as follows:

    • The layout, length, and number of members of the volume are determined by the field's layout, length, and memberCount of parameter volumeSpec.

    • The members of the volume MUST be created on the disks passed in diskList.

    • The length of each member is determined by the field length of the corresponding DISK_SPEC structure passed in diskList.

    • If the field needContiguous is set to TRUE in a DISK_SPEC structure passed in diskList, the server MUST allocate a contiguous disk region for the corresponding member. Otherwise, the server MAY allocate several noncontiguous disk regions.

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

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

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

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

  6. Fill in the tinfo output parameter:

    • Field tinfo.storageId MUST be set to the identifier of the dynamic volume object.<100>

      TASK_INFO member

      Required for this operation

      TASK_INFO::id

      Required.

      TASK_INFO::storageId

      Required.

      TASK_INFO::createTime

      Not required.<101>

      TASK_INFO::clientID

      Not required.<102>

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

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

  8. Send the task completion notification.

Note The server MAY decide not to wait for the formatting to complete before returning the response to the client.<104> All rules for handling asynchronous tasks apply here.

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

  1. Create a new dynamic volume object.

  2. Modify the disk objects where the new volume resides to account for the change in region allocation.

  3. Create new disk region objects that correspond to the volume members.

  4. Modify or delete the free disk region objects where the volume members were created to account for the allocation of volume members in those regions.

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

If the format operation is 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 dynamic volume object to account for the change of status.