Share via

3.2.4.4.1.2 IVolumeClient::EnumDiskRegions (Opnum 4)

  • Article

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

 HRESULT EnumDiskRegions(
   [in] LdmObjectId diskId,
   [in, out] unsigned long* numRegions,
   [out, size_is(,*numRegions)] REGION_INFO** 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 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] section 2.1; 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 the disk specified by diskId is in the list of storage objects.

  • Verify that numRegions and regionList are 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:

  1. Enumerate all disk region objects residing on the specified disk.

  2. Allocate a buffer large enough to contain REGION_INFO structures describing all regions residing 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.

    All fields MUST contain meaningful values. If no volume is associated, volId is 0. If there is no associated task, taskId is zero.

  4. Populate each REGION_INFO 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 structures in the buffer MUST be returned in the output parameter numRegions.

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