3.2.4.4.1.26 IVolumeClient::CreateVolume (Opnum 30)

  • Article

The CreateVolume method creates a dynamic volume on the specified list of disks. This is a synchronous task.

 HRESULT CreateVolume(
   [in] VOLUME_SPEC volumeSpec,
   [in] unsigned long diskCount,
   [in, size_is(diskCount)] DISK_SPEC* diskList,
   [out] TASK_INFO* tinfo
 );

volumeSpec: A VOLUME_SPEC structure that defines the parameters of 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.

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).<92>

Upon receiving this message, the server MUST validate parameters:

  • Verify that diskCount is not 0 and diskList is not NULL.

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

  • 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 the dynamic volume as follows:

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

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

    • The approximate 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.<93>

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

  3. Fill in the tinfo output parameter:

    • Field tinfo.storageId MUST be set to the identifier of the new dynamic volume object.

      TASK_INFO member

      Required for this operation

      TASK_INFO::id

      Required.

      TASK_INFO::storageId

      Required if the method succeeds.

      TASK_INFO::createTime

      Not required.<94>

      TASK_INFO::clientID

      Not required.<95>

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

  4. Return a response to the client containing tinfo and the status of the operation.<97>

  5. Send the task completion notification.

If the operation 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.<98>