3.2.4.4.3.48 IVolumeClient3::EncapsulateDiskEx (Opnum 51)

  • Article

The EncapsulateDiskEx method converts the specified basic disks to dynamic disks. This is a synchronous task.

 HRESULT EncapsulateDiskEx(
   [in] unsigned long affectedDiskCount,
   [in, size_is(affectedDiskCount)] 
     DISK_INFO_EX* affectedDiskList,
   [in] unsigned long affectedVolumeCount,
   [in, size_is(affectedVolumeCount)] 
     VOLUME_INFO* affectedVolumeList,
   [in] unsigned long affectedRegionCount,
   [in, size_is(affectedRegionCount)] 
     REGION_INFO_EX* affectedRegionList,
   [out] unsigned long* encapInfoFlags,
   [out] TASK_INFO* tinfo
 );

affectedDiskCount: The number of elements passed in the affectedDiskList array.

affectedDiskList: An array of DISK_INFO_EX structures that specifies the disks to be encapsulated.

affectedVolumeCount: The number of elements passed in the affectedVolumeList array.

affectedVolumeList: An array of VOLUME_INFO structures that represents the volumes affected by the encapsulation. If the number of affect volumes is zero, a pointer to a zero-length array MUST be passed. This pointer MUST NOT be input as NULL.

affectedRegionCount: The number of elements passed in the affectedRegionList array.

affectedRegionList: An array of REGION_INFO_EX structures that represents the regions affected by the encapsulation. If the number of affect regions is zero, a pointer to a zero-length array MUST be passed. This pointer MUST NOT be input as NULL.

encapInfoFlags: Bitmap of flags that provides information about the encapsulation. The value of this field is generated by combining zero or more of the following applicable flags with a logical OR operation.

Value

Meaning

ENCAP_INFO_CANT_PROCEED

0x00000001

Encapsulation for disk did not succeed. Inspect the other values of encapInfoFlags to determine the reason.

ENCAP_INFO_NO_FREE_SPACE

0x00000002

The volume manager could not find sufficient free space on the disk for encapsulation.

ENCAP_INFO_BAD_ACTIVE

0x00000004

The disk contains an active partition from which the current operating system was not started.

ENCAP_INFO_UNKNOWN_PART

0x00000008

The volume manager was unable to determine the type of a partition on the disk.

ENCAP_INFO_FT_UNHEALTHY

0x00000010

The disk contains an unhealthy FT set volume.

ENCAP_INFO_FT_QUERY_FAILED

0x00000020

The volume manager was unable to obtain information about an FT set volume on the disk.

ENCAP_INFO_REBOOT_REQD

0x00000100

Encapsulation of the disk will require a restart of the computer.

ENCAP_INFO_CONTAINS_FT

0x00000200

The disk is part of an FT set volume.

ENCAP_INFO_VOLUME_BUSY

0x00000400

The disk is currently in use.

ENCAP_INFO_PART_NR_CHANGE

0x00000800

Encapsulation of the disk requires modification of the boot configuration.

ENCAP_INFO_MIXED_PARTITIONS

0x00001000

Encapsulation of a GPT disk that contains basic partitions mixed with nonbasic partitions is not supported.

ENCAP_INFO_OPEN_FAILED

0x00002000

Could not open a volume that resides on a disk in the set of disks specified for encapsulation.

tinfo: A pointer to a TASK_INFO structure that the client can use to track the progress of the request.

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 affectedDiskList is not NULL and affectedDiskCount is not 0.

  2. For each DISK_INFO_EX structure specified by affectedDiskList, verify that the disk specified by diskId is in the list of storage objects and that lastKnownState matches the LastKnownState field of the object.

  3. Verify that no other basic disks need to be encapsulated together with the disks specified by affectedDiskList.

  4. Verify that affectedVolumeList is not NULL. If affectedVolumeCount is zero, a valid pointer to a zero-length array for the affectVolumeList MUST be passed in.

  5. Verify that affectedRegionList is not NULL. If affectedRegionCount is zero, a valid pointer to a zero-length array for the affectRegionList MUST be passed in.

  6. Verify that the list of basic volumes specified by affectedVolumeList matches the set of basic volumes residing on the disks specified by affectedDiskList.

  7. Verify that encapInfoFlags is not NULL.

  8. 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. Convert the basic disks specified by affectedDiskList to dynamic:

  2. Wait for the conversion to 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.<216>

    TASK_INFO::clientID

    Not required.<217>

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

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

  5. Send the task completion notification.<219>

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 converted disk objects to account for the change in type.

  2. Create new dynamic volume objects that correspond to the new dynamic volumes.

  3. Create new disk region objects for the new dynamic disks.

  4. Delete disk region objects of the old basic disks.<220>

  5. Modify drive letter objects to account for the change of volume owning them.

  6. Modify file system objects to account for the change of volume owning them.

If the boot partition is among the disks being encapsulated, the server MUST store boot partition change information on persistent storage (registry). The information MUST contain the old (pre-encapsulation) and new (post-encapsulation) partition number of the boot partition. The information is useful in case the client sends an IVolumeClient3::QueryChangePartitionNumbers message.