3.4.5.2.23.2 IVdsDisk3::QueryFreeExtents (Opnum 6)

  • Article

The QueryFreeExtents method enumerates a disk's free extents.Returns all free extents on the disk and aligns them to the alignment value supplied in the ulAlign parameter. If there is no alignment value supplied, QueryFreeExtents aligns the free extents based on the default alignment values.

 HRESULT QueryFreeExtents(
   [in] ULONG ulAlign,
   [out, size_is(,*plNumberOfFreeExtents)] 
     VDS_DISK_FREE_EXTENT **ppFreeExtentArray,
   [out] LONG *plNumberOfFreeExtents
 );

ulAlign: The alignment value. If ulAlign is 0, the default alignment value is used.

ppFreeExtentArray: Pointer to an array of VDS_DISK_FREE_EXTENT structures that, if the operation is successful, receives the array of disk extent structures.

plNumberOfFreeExtents: Pointer to a variable that, if the operation is successfully completed, receives the total number of elements in ppFreeExtentArray.

Return Values: QueryFreeExtents MUST return zero to indicate success, or an implementation-specific, nonzero error code to indicate failure.

Free extents are not returned for CD/DVD, or super floppy devices.

If the disk has no partition format (it is not formatted as either MBR or GPT), then this method MUST return VDS_E_DISK_NOT_INITIALIZED.

When the server receives this message, it MUST validate the following parameters:

  • Verify that the ppFreeExtentArray parameter is not NULL.

  • Verify that the plNumberOfFreeExtents parameter is not NULL.

The server MUST point ppFreeExtentArray to an array of VDS_DISK_FREE_EXTENT structures that contain information about each disk extent on the disk, point plNumberOfFreeExtents to the number of elements in the array, and return an HRESULT indicating failure or success.