3.2.4.4.1.34 IVolumeClient::SplitMirror (Opnum 38)

  • Article

The SplitMirror method splits a dynamic mirrored volume into two independent simple volumes, one with the identifier and drive letter of the original volume and the other with a different identifier and drive letter. This is a synchronous task.

 HRESULT SplitMirror(
   [in] LdmObjectId volumeId,
   [in] hyper volumeLastKnownState,
   [in] LdmObjectId diskId,
   [in] hyper diskLastKnownState,
   [in] wchar_t letter,
   [in] hyper letterLastKnownState,
   [in, out] TASK_INFO* tinfo
 );

volumeId: Specifies the OID of the volume to split.

volumeLastKnownState: Volume's last known modification sequence number.

diskId: Specifies the object identifier of the disk to break away from the volume specified by volumeId.

diskLastKnownState: Last known modification sequence number of the disk to split off.

letter: Drive letter to assign to the disk identified by diskId. If no drive letter is needed for the volume, the value of this field MUST be either a 2-byte null character or the Unicode SPACE character.

letterLastKnownState: Last known modification sequence number of the drive letter that is being assigned to the disk to split.

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 diskId is in the list of storage objects and check whether diskLastKnownState matches the LastKnownState field of the object.

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

  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 remove the mirror of the volume specified by volumeId residing on the disk specified by diskId. If the client sets the TASK_INFO::error parameter to LDM_DEVICE_IN_USE, the server MUST remove the mirror of the volume, even if the volume is in use. If the client does not set the TASK_INFO::error parameter to LDM_DEVICE_IN_USE and if the volume is in use, the server MUST fail the operation immediately, returning the LDM_E_VOLUME_IN_USE error as its response to the client.

  2. Transform the removed member into a standalone dynamic volume.

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

  4. Wait for the preceding sequence to either succeed or fail.

  5. 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.<124>

    TASK_INFO::clientID

    Not required.<125>

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

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

  7. Send the task completion notification.

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

  1. Modify the old dynamic volume object to account for the change in layout and number of members.

  2. Create a new dynamic volume object for the new volume.

  3. Modify the disk region objects split from the old volume to account for their migration to the new volume.

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

  • Modify the drive letter object, if specified by letter, to mark it as in use by the new volume.

  • Create a new file system object for the new volume.<127>