3.2.4.4.1.44 IVolumeClient::GetEncapsulateDiskInfo (Opnum 53)

  • Article

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:

  1. Verify that diskCount is not 0 and diskSpecList is not NULL.

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

  3. Verify that encapInfoFlags is not NULL.

  4. Verify that affectedDiskCount, affectedDiskList, and affectedDiskFlags are not NULL.

  5. Verify that affectedVolumeCount and affectedVolumeList are not NULL.

  6. Verify that affectedRegionCount and affectedRegionList are not NULL.

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

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

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

  3. Populate each DISK_INFO structure in the buffer with information about the disk.

  4. The buffer MUST be returned to the client in the output parameter affectedDiskList.

  5. The number of DISK_INFO structures in the buffer MUST be returned to the client in the output parameter affectedDiskCount.

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

  7. Populate the second buffer with the bitmaps of flags of the disks.

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

  9. Enumerate all the FT volumes that reside on the disks returned in affectedDiskList from the list of storage objects.

  10. Allocate a third buffer large enough to contain VOLUME_INFO structures that describe the enumerated FT volumes.

  11. Populate each VOLUME_INFO structure in the third buffer with information about the FT volume.

  12. The third buffer MUST be returned to the client in the output parameter affectedVolumeList.

  13. The number of VOLUME_INFO structures in the third buffer MUST be returned to the client in the output parameter affectedVolumeCount.

  14. Enumerate all the disk regions that reside on the disks returned in affectedDiskList from the list of storage objects, excluding free regions.

  15. Allocate a fourth buffer large enough to contain REGION_INFO structures that describe the enumerated disk regions.

  16. Populate each REGION_INFO structure in the fourth buffer with information about the disk region.

  17. The fourth buffer MUST be returned to the client in the output parameter affectedRegionList.

  18. The number of REGION_INFO structures in the fourth buffer MUST be returned to the client in the output parameter affectedRegionCount.

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

  20. The bitmap of flags MUST be returned to the client in the output parameter encapInfoFlags.

  21. Return a response that contains the output parameters mentioned previously and the status of the operation.

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