3.4.5.2.32.10 IVdsVolume::SetFlags (Opnum 12)

  • Article

The SetFlags method assigns flags to a volume.<120>

 HRESULT SetFlags(
   [in] unsigned long ulFlags,
   [in] long bRevertOnClose
 );

ulFlags: The combination of any values, by using a bitwise OR operator, that are defined in the VDS_VOLUME_FLAG enumeration.<121>

bRevertOnClose: A Boolean that determines whether the flags SHOULD<122> be temporarily set. If they are temporarily set, VDS_VF_READONLY, VDS_VF_HIDDEN, VDS_VF_NO_DEFAULT_DRIVE_LETTER, and VDS_VF_SHADOW_COPY are the only valid flags that can be set, and the server reverts the flags after the client releases its last reference to the volume object.

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 parameters:

  • Verify that ulFlags contains only those valid flags defined in the VDS_VOLUME_FLAG enumeration. If bRevertOnClose is set, then verify that ulFlags only contains VDS_VF_READONLY, VDS_VF_HIDDEN, VDS_VF_NO_DEFAULT_DRIVE_LETTER, and/or VDS_VF_SHADOW_COPY.

  • If bRevertOnClose is set, verify that the volume object does not have flags that were previously set with bRevertOnClose and are yet to be reverted on close.

  • If bRevertOnClose is not set:

    • Verify that the flags being set do not contain a flag that was previously set with bRevertOnClose and is yet to be reverted on close.

    • Verify that ulFlags only contains VDS_VF_HIDDEN, VDS_VF_READONLY, VDS_VF_NO_DEFAULT_DRIVE_LETTER, VDS_VF_SHADOW_COPY, and/or VDS_VF_INSTALLABLE.<123>

The server MUST perform the following:

  • If the ulFlags parameter specifies that the VDS_VF_READONLY or VDS_VF_HIDDEN flags be set on a volume located on an MBR disk, and that disk contains a critical volume, such as the system, boot, hibernation, page file, or crash dump volumes, then the server MUST fail this method and return VDS_E_OPERATION_DENIED.

  • Set the volume flags specified by ulFlags.

  • If bRevertOnClose is set, the server MUST be prepared to automatically revert the volume flags if a client releases the last reference to the volume object.

  • For each callback object registered in the list of callback objects, call the callback object's IVdsAdviseSink::OnNotify() 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_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.

  • Return an HRESULT indicating failure or success.