3.2.4.4.1.44 IVolumeClient::GetEncapsulateDiskInfo (Opnum 53)
The GetEncapsulateDiskInfo method gathers the information needed to convert the specified basic disks to dynamic disks. This is a synchronous task.
-
HRESULT GetEncapsulateDiskInfo( [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** 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** affectedRegionList, [out] TASK_INFO* tinfo );
diskCount: Number of elements passed in the diskSpecList array.
diskSpecList: Array of DISK_SPEC structures that specifies the disks to be encapsulated.
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 applicable flags defined as follows with a logical OR operation.
-
Value
Meaning
ENCAP_INFO_CANT_PROCEED
0x00000001
Encapsulation for 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 started.
ENCAP_INFO_UNKNOWN_PART
0x00000008
Volume manager was unable to determine the type of a partition on 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_FT_HAS_RAID5
0x00000040
Disk is part of an FT RAID-5 set, which this interface does not support for encapsulation.
ENCAP_INFO_FT_ON_BOOT
0x00000080
Disk is both 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
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.
affectedDiskCount: Pointer to the number of disks that will be affected by the encapsulation.
affectedDiskList: Pointer to an array of new DISK_INFO structures that represents the disks that will be affected by the encapsulation. Memory for the array is allocated by the server and freed by the client.
affectedDiskFlags: Pointer to an array of bitmaps of flags that provides information about the disks that will be affected by the encapsulation. Memory for the array is allocated by the server and freed by the client. The value of this field is a logical 'OR' of 0 or more of the following applicable flags.
-
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
Disk contains an unknown volume type.
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 empty 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 different types of partitions.
affectedVolumeCount: Pointer to the number of volumes that will be affected by the encapsulation.
affectedVolumeList: Pointer to an array of VOLUME_INFO structures that represents the volumes that will be affected by the encapsulation. Memory for the array is allocated by the server and freed by the client.
affectedRegionCount: Pointer to the number of regions that will be affected by the encapsulation.
affectedRegionList: Pointer to an array of REGION_INFO structures that represents the regions that will be affected by the encapsulation. Memory for the array is allocated by the server and freed by the client.
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:
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 flags is not NULL.
If parameter validation fails, the server MUST fail the operation immediately, returning an appropriate error as its response to the client.<163>
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. If disks that have existing FT Disk volume sets are being encapsulated, the server must get a list of volume extents for all volumes that have at least one extent on the input disks. Then walk through the list of volume extents and add it for each extent, if the disk on which the extent is located is not in the diskSpecList.
Allocate a buffer large enough to contain DISK_INFO structures that describe all basic disks that need to be encapsulated together (including the disks specified by diskSpecList).
Populate each DISK_INFO 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 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 describe 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, excluding free regions.
Allocate a fourth buffer large enough to contain REGION_INFO structures that describe the enumerated disk regions.
Populate each REGION_INFO 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 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 describing 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.
Fill in the tinfo output parameter. This is a synchronous task.
The tinfo values MUST be set as follows.
TASK_INFO member
Required for this operation
TASK_INFO::id
Required.
TASK_INFO::storageId
Not required.
TASK_INFO::createTime
Not required.<164>
TASK_INFO::clientID
Not required.<165>
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.<166>
The server MUST NOT change the list of storage objects as part of processing this message.