3.2.4.4.3.47 IVolumeClient3::GetEncapsulateDiskInfoEx (Opnum 50)

Article
10/30/2020

The GetEncapsulateDiskInfoEx method gathers the information needed to convert the specified basic disks to dynamic disks.

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

diskCount: Number of elements passed in the diskSpecList array.

diskSpecList: Array of DISK_SPEC structures that specify the disks to be encapsulated. Memory for the array is allocated and freed by the client.

encapInfoFlags: Bitmap of flags that returns information about encapsulating the disks specified in diskSpecList. 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 the disk will not succeed. The other flags specify the reason.
ENCAP_INFO_NO_FREE_SPACE 0x00000002	Volume manager could not find sufficient free space on the disk for encapsulation.
ENCAP_INFO_BAD_ACTIVE 0x00000004	Disk contains an active partition from which the current operating system was not started.
ENCAP_INFO_UNKNOWN_PART 0x00000008	Volume manager was unable to determine the type of a partition on the disk because of corruption or other errors reading the disk. For example, any error that prevents the partition information from being read, or the partition is neither GPT nor MBR, or an OEM partition is found that is not at the beginning of the disk.
ENCAP_INFO_FT_UNHEALTHY 0x00000010	Disk contains an FT set volume that is not functioning properly.
ENCAP_INFO_FT_QUERY_FAILED 0x00000020	Volume manager was unable to obtain information about an FT set volume on the disk.
ENCAP_INFO_REBOOT_REQD 0x00000100	Encapsulation of the disk requires a restart of the computer.
ENCAP_INFO_CONTAINS_FT 0x00000200	Disk is part of an FT set volume.
ENCAP_INFO_VOLUME_BUSY 0x00000400	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.

affectedDiskCount: Pointer to the number of disks that will be affected by the encapsulation.

affectedDiskList: Pointer to an array of new DISK_INFO_EX structures that represent the disks that will be affected by the encapsulation.

affectedDiskFlags: Pointer to an array of bitmaps of flags that provides information about the disks that will be affected by 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
CONTAINS_FT 0x00000001	Disk contains an FT set volume.
CONTAINS_RAID5 0x00000002	Disk contains part of an FT RAID-5 set.
CONTAINS_REDISTRIBUTION 0x00000004	Not used.
CONTAINS_BOOTABLE_PARTITION 0x00000008	Disk contains a bootable partition.
CONTAINS_LOCKED_PARTITION 0x00000010	Disk contains a locked partition.
CONTAINS_NO_FREE_SPACE 0x00000020	Disk is full.
CONTAINS_EXTENDED_PARTITION 0x00000040	Disk contains an extended partition.
PARTITION_NUMBER_CHANGE 0x00000080	A partition number on the disk has changed.
CONTAINS_BOOTINDICATOR 0x00000100	Disk contains the active partition.
CONTAINS_BOOTLOADER 0x00000200	Disk contains the boot loader.
CONTAINS_SYSTEMDIR 0x00000400	Partition contains the system directory.
CONTAINS_MIXED_PARTITIONS 0x00000800	Partition contains partitions that will not be converted to dynamic.

affectedVolumeCount: Pointer to the number of volumes that will be affected by the encapsulation.

affectedVolumeList: Pointer to an array of VOLUME_INFO structures that represent the volumes that will be affected by the encapsulation.

affectedRegionCount: Pointer to the number of regions that will be affected by the encapsulation.

affectedRegionList: Pointer to an array of REGION_INFO_EX structures that represent the regions that will be affected by the encapsulation.

tinfo: Pointer to a TASK_INFO structure 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:

Verify that diskCount is not 0 and diskSpecList is not NULL.
For each DISK_SPEC structure specified in diskSpecList, 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.
Verify that encapInfoFlags is not NULL.
Verify that affectedDiskCount, affectedDiskList, and affectedDiskFlags are not NULL.
Verify that affectedVolumeCount and affectedVolumeList are not NULL.
Verify that affectedRegionCount and affectedRegionList are not NULL.
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 compose a response to the client as follows:

Identify other basic disks from the list of storage objects that need to be encapsulated together with the basic disks specified by diskSpecList.
Allocate a buffer large enough to contain DISK_INFO_EX structures that describe all basic disks that need to be encapsulated together (including the disks specified by diskSpecList).
Populate each DISK_INFO_EX structure in the buffer with information about the disk.
The buffer MUST be returned to the client in the output parameter affectedDiskList.
The number of DISK_INFO_EX structures in the buffer MUST be returned to the client in the output parameter affectedDiskCount.
Allocate a second buffer large enough to contain bitmaps of flags, one for each disk returned in affectedDiskList, that describes disk conditions that are of interest to clients in the context of encapsulation.
Populate the second buffer with the bitmaps of flags of the disks.
The second buffer MUST be returned to the client in the output parameter affectedDiskFlags. Note that the number of elements in the buffer is the same as the count of disks, which is returned in affectedDiskCount.
Enumerate all the FT volumes that reside on the disks returned in affectedDiskList from the list of storage objects.
Allocate a third buffer large enough to contain VOLUME_INFO structures that describe the enumerated FT volumes.
Populate each VOLUME_INFO structure in the third buffer with information about the FT volume.
The third buffer MUST be returned to the client in the output parameter affectedVolumeList.
The number of VOLUME_INFO structures in the third buffer MUST be returned to the client in the output parameter affectedVolumeCount.
Enumerate all the disk regions that reside on the disks returned in affectedDiskList from the list of storage objects.
Allocate a fourth buffer large enough to contain REGION_INFO_EX structures that describe the enumerated disk regions.
Populate each REGION_INFO_EX structure in the fourth buffer with information about the disk region.
The fourth buffer MUST be returned to the client in the output parameter affectedRegionList.
The number of REGION_INFO_EX structures in the fourth buffer MUST be returned to the client in the output parameter affectedRegionCount.
Populate a 32-bit signed integer bitmap of flags that describes conditions that will prevent the overall encapsulation to proceed, or might be of interest to the client in the context of encapsulation. If the encapsulation cannot proceed, the server MUST set the ENCAP_INFO_CANT_PROCEED flag, and then set other flags as appropriate to account for the reasons why the encapsulation is not possible.
The bitmap of flags MUST be returned to the client in the output parameter encapInfoFlags.
Return a response that contains the output parameters mentioned previously and the status of the operation.

The server MUST NOT change the list of storage objects as part of processing this message.

3.2.4.4.3.47 IVolumeClient3::GetEncapsulateDiskInfoEx (Opnum 50)

Additional resources