Share via

3.2.4.4.1.45 IVolumeClient::EncapsulateDisk (Opnum 54)

  • Article

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

 HRESULT EncapsulateDisk(
   [in] unsigned long affectedDiskCount,
   [in, size_is(affectedDiskCount)] 
     DISK_INFO* affectedDiskList,
   [in] unsigned long affectedVolumeCount,
   [in, size_is(affectedVolumeCount)] 
     VOLUME_INFO* affectedVolumeList,
   [in] unsigned long affectedRegionCount,
   [in, size_is(affectedRegionCount)] 
     REGION_INFO* 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 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 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 provide information about the encapsulation. The value of this field is a logical 'OR' of zero or more of the following applicable flags.

Value

Meaning

ENCAP_INFO_CANT_PROCEED

0x00000001

Encapsulation for disk did not succeed. The other flags specify 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_FT_HAS_RAID5

0x00000040

The disk is part of an FT RAID-5 set, which this interface does not support for encapsulation.

ENCAP_INFO_FT_ON_BOOT

0x00000080

The disk is part of an FT set volume and bootable, which this interface does not support for encapsulation.

ENCAP_INFO_REBOOT_REQD

0x00000100

Encapsulation of the disk requires 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.

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

  2. For each DISK_INFO 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. For each DISK_INFO structure specified by affectedDiskList, verify that the disk specified by diskId is not a GPT disk.

  4. For each REGION_INFO structure specified by affectedRegionList, verify that the region's style field does have the value PARTITIONSTYLE_GPT.

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

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

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

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

  9. Verify that encapInfoFlags is not NULL.

  10. 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 either succeed or fail.

  3.  Fill in the encapInfoFlags output parameter.

  4. 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.<167>

    TASK_INFO::clientID

    Not required.<168>

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

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

  6. Send the task completion notification.<170>

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

  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 and if the partition number of the boot partition changes during the disk encapsulation, 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 IVolumeClient::QueryChangePartitionNumbers message. The IVolumeClient::QueryChangePartitionNumbers method will return the original partition number and the new partition number. This information MAY be used to update boot settings if necessary.<172>