Share via

3.2.4.4.3.2 IVolumeClient3::EnumDiskRegionsEx (Opnum 4)

  • Article

The EnumDiskRegionsEx method enumerates all used and free regions of a specified disk.

 HRESULT EnumDiskRegionsEx(
   [in] LdmObjectId diskId,
   [in, out] unsigned long* numRegions,
   [out, size_is(,*numRegions)] REGION_INFO_EX** regionList
 );

diskId: Specifies the OID of the disk for which regions are being enumerated.

numRegions: Pointer to the number of regions in regionList.

regionList: Pointer to an array of REGION_INFO_EX structures.

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 numRegions and regionList are not NULL.

  2. Verify that the disk specified by diskId is in the list of storage objects.

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:

  1. Enumerate all disk region objects that reside on the specified disk.

  2. Allocate a buffer large enough to contain REGION_INFO_EX structures that describes all regions that reside on the disk.

  3. The buffer MUST be populated with regions in the ascending order of the byte offset of the region relative to the beginning of the disk.

  4. Populate each REGION_INFO_EX structure in the buffer with information about the region.

  5. The buffer MUST be returned to the client in the output parameter regionList.

  6. The number of REGION_INFO_EX structures in the buffer MUST be returned in the output parameter numRegions.

  7. Return a response to the client containing 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.