The Clean method cleans a disk.

 HRESULT Clean(
   [in] long bForce,
   [in] long bForceOEM,
   [in] long bFullClean,
   [out] IVdsAsync** ppAsync
 );

bForce: A Boolean value that indicates whether the cleaning operation will be forced. If set, the method attempts to clean the disk, even if data volumes or ESP partitions are present.

bForceOEM: A Boolean value that indicates whether the cleaning operation of an OEM partition will be forced. If the disk contains an OEM partition, but bForceOEM is not set, the operation SHOULD fail. If the value is set, the method attempts to clean the disk, even if OEM partitions are present.<99>

bFullClean: A Boolean value specifying whether the cleaning operation removes all the data from the disk.

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.

Note This method is not valid on CD/DVD devices.

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

• Verify that ppAsync is not NULL.

The server MUST perform the following:

• If this method is called against a disk which contains data volume extents or an EFI system partition (an ESP), and the bForce flag is not set, then this method returns VDS_E_DISK_NOT_EMPTY for a dynamic disk.<100>

• If this method is called against a disk which contains a protected OEM partition, and the bForceOEM flag is not set, then this method MUST return VDS_E_DISK_NOT_EMPTY for a dynamic disk.<101>

• Create a new async object implementing the IVdsAsync interface with an output type of VDS_ASYNCOUT_CLEAN and set the pointer referenced by ppAsync 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.

• Clean the disk, removing all partition information, following the parameters specified to the method.

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

  • If TRUE was specified for bFullClean, but the server could not clean particular sectors, the return code MUST be set to VDS_S_DISK_PARTIALLY_CLEANED.

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

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

• If the disk is a removable media disk, for each callback object registered in the list of callback objects, call the callback object's IVdsAdviseSink::OnNotify (Opnum 3) method with a VDS_NOTIFICATION structure with 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_DEPART.

    • volumeId is the VDS_OBJECT_ID of the volume object corresponding to the removable media drive.

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

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

• For each callback object registered in the list of callback objects, call the callback object's IVdsAdviseSink::OnNotify (Opnum 3) method with a VDS_NOTIFICATION structure with the following attributes:

  • objectType member is VDS_NTT_DISK.

  • Disk member is a VDS_DISK_NOTIFICATION with the following attributes:

    • ulEvent is VDS_NF_DISK_DEPART.

    • diskId is the VDS_OBJECT_ID of this disk object.

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.

The server MAY allow the clean operation to be canceled through the IVdsAsync interface.<102>