3.4.5.2.37.2 IVdsVolumeShrink::Shrink (Opnum 4)

  • Article

The Shrink method shrinks the volume and all plexes, and then returns the released extents. The Shrink method compacts the files toward the beginning of the volume, creating free space at the end of the volume. The Shrink method also truncates the file system, reducing its size, and then truncates the partition or dynamic volume.

 HRESULT Shrink(
   [in] ULONGLONG ullDesiredNumberOfReclaimableBytes,
   [in] ULONGLONG ullMinNumberOfReclaimableBytes,
   [out] IVdsAsync** ppAsync
 );

ullDesiredNumberOfReclaimableBytes: The desired number of bytes to be reclaimed from the volume. The method SHOULD attempt to reclaim the desired number of bytes as specified by this parameter. If it is unable to do so, it SHOULD attempt to reclaim a size smaller than ullDesiredNumberOfReclaimableBytes but greater than or equal to ullMinNumberOfReclaimableBytes. Additionally ullMinNumberOfReclaimableBytes MUST be at least 1048576 bytes (1 MB). The actual number of bytes reclaimed is always a multiple of the file system cluster size, which is in turn a multiple of the disk sector size.

ullMinNumberOfReclaimableBytes: The minimum number of bytes to be reclaimed from the volume. If the method cannot reclaim at least the minimum number of bytes as specified by this parameter, the method MUST fail and MUST NOT reclaim any bytes.

ppAsync: A pointer to an IVdsAsync interface that, if the operation is successfully completed, receives the IVdsAsync interface to monitor and control this operation. Callers MUST release the interface when they are done with it.

Return Values: The method MUST return zero or a non-error HRESULT (as specified in [MS-ERREF]) to indicate success, or return an implementation-specific nonzero error code to indicate failure. For the HRESULT values predefined by the Virtual Disk Service Remote Protocol, see section 2.2.3.

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

  • Verify that ppAsync is not NULL.<137>

  • Verify that ullDesiredNumberOfReclaimableBytes is not zero.

  • Verify that ullDesiredNumberOfReclaimableBytes is greater than or equal to ullMinNumberOfReclaimableBytes.

The server MUST perform the following:

  • Create a new async object implementing the IVdsAsync interface with an output type of VDS_ASYNCOUT_SHRINKVOLUME and set the pointer ppAsync references to the interface.

  • Return an HRESULT indicating failure or success. Any errors encountered up through this point in processing the operation are returned in this HRESULT.

The server MUST then perform the following in sequence. Errors generated in this sequence of steps are returned in the pHrResult parameter to the IVdsAsync::Wait or IVdsAsyncQueryStatus methods.

  • The file system <138> needs to shrink, if the file system on the volume supports shrinking following the parameters specified to the method.

  • Shrink the volume and all its plexes following the parameters specified to the method.

  • Release the extents that have been reclaimed and mark them as free extents.

  • For each callback object that is registered in the list of callback objects, call the callback object's IVdsAdviseSink::OnNotify() method by using a VDS_NOTIFICATION structure that has the following attributes:

    • objectType member is VDS_NTT_VOLUME.

    • Volume member is a VDS_VOLUME_NOTIFICATION with the following attributes:

      • ulEvent is VDS_NF_VOLUME_MODIFY.

      • volumeId is the VDS_OBJECT_ID of this volume object.

      • plexId is NULL GUID, but it is not relevant when ulEvent is VDS_NF_VOLUME_MODIFY.

      • ulPercentCompleted range is 0-100 and is implementation-specific; however, it is not relevant when ulEvent is VDS_NF_VOLUME_MODIFY.

  • Set the return code in the async object to an HRESULT indicating failure or success.

  • If the task completed successfully, set the percentage completed value in the async object to 100.

  • Set the signal state in the async object to TRUE.

The server MUST update the percentage completed value periodically during the preceding sequence. How often the percentage completed is updated, and at what point in the sequence, is implementation-specific.