3.2.4.4.1.30 IVolumeClient::GrowVolume (Opnum 34)

  • Article

The GrowVolume method increases the length of a specified dynamic volume by appending extents from the specified disks to it. This is a synchronous task.

 HRESULT GrowVolume(
   [in] LdmObjectId volumeId,
   [in] VOLUME_SPEC volumeSpec,
   [in] unsigned long diskCount,
   [in, size_is(diskCount)] DISK_SPEC* diskList,
   [in] boolean force,
   [out] TASK_INFO* tinfo
 );

volumeId: Specifies the OID of the volume whose size is being changed.

volumeSpec: A VOLUME_SPEC structure that defines the parameters of the changed volume, including its new expected length.

diskCount: Number of elements passed in diskList.

diskList: Array of DISK_SPEC structures that specifies the list of disk extents to be appended to the volume. Memory for the array is allocated and freed by the client. All fields MUST be filled out.

force: Boolean value that determines whether the volume is extended or not in case it cannot be locked.

Value

Meaning

FALSE

0

Volume is not extended unless it is locked.

TRUE

1

Volume is extended whether it is locked or unlocked.

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

Upon receiving this message, the server MUST validate parameters:

  1. Verify that the dynamic volume specified by volumeId is in the list of storage objects, and check whether the field volumeSpec.lastKnownState matches the field LastKnownState of the object.

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

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

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

    • The new length of the volume is determined by the field length of parameter volumeSpec.

    • New members of the volume MUST be created on the disks passed in diskList and concatenated to the volume, as specified by the force parameter.

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

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

  3. Fill in the tinfo output parameter.

    TASK_INFO member

    Required for this operation

    TASK_INFO::id

    Required.

    TASK_INFO::storageId

    Not required.

    TASK_INFO::createTime

    Not required.<106>

    TASK_INFO::clientID

    Not required.<107>

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

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

  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. Modify the dynamic volume object to account for the change in size and number of members.

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

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

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