3.2.4.4.1.32 IVolumeClient::AddMirror (Opnum 36)

  • Article

The AddMirror method adds a mirror to the specified dynamic volume. This is a synchronous task.

 HRESULT AddMirror(
   [in] LdmObjectId volumeId,
   [in] hyper volumeLastKnownState,
   [in] DISK_SPEC diskSpec,
   [in, out] int* diskNumber,
   [out] int* partitionNumber,
   [out] TASK_INFO* tinfo
 );

volumeId: Specifies the OID of the volume to which the mirror is being added.

volumeLastKnownState: Volume's last known modification sequence number.

diskSpec: A DISK_SPEC structure that defines the disk to add as the mirror.

diskNumber: Unused. This parameter MUST be set to 0 by the client and MUST be ignored by the server.

partitionNumber: Pointer to the partition number of the newly added mirror.

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 the dynamic volume specified by volumeId is in the list of storage objects, and check whether the field volumeLastKnownState matches the field LastKnownState of the object.

  2. Verify that the disk specified by diskSpec.diskId is in the list of storage objects, and check whether diskSpec.lastKnownState matches the LastKnownState field of the object.

  3. Verify that partitionNumber is not NULL.

  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. Add a mirror to the dynamic volume as follows:

    • A new member of the volume MUST be created on the disk specified by diskSpec.diskId and added to the volume as a mirror.

    • The length of the member is determined by the length of the volume field.

    • If the field diskSpec.needContiguous is set to TRUE, the server MUST allocate a contiguous disk region for the new member. Otherwise, the server MAY allocate several noncontiguous disk regions.

  2. Wait for the mirror addition to either succeed or fail.

  3. Fill the partitionNumber output parameter as follows:

    • If the dynamic volume is a boot volume, set partitionNumber to the partition number of the new volume members.

    • Otherwise, set partitionNumber to 0.

  4. Fill in the tinfo output parameter.

    TASK_INFO member

    Required for this operation

    TASK_INFO::id

    Required<115>.

    TASK_INFO::storageId

    Not required.

    TASK_INFO::createTime

    Not required.<116>

    TASK_INFO::clientID

    Not required.<117>

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

  5. Return a response to the client containing tinfo, partitionNumber, and the status of the operation.

  6. Send the task completion notification.<119>

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 layout and number of members.

  2. Modify the disk object where the new volume member was created to account for the change in region allocation.

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

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