3.2.4.4.1.20 IVolumeClient::FreeDriveLetter (Opnum 23)

  • Article

The FreeDriveLetter method unassigns a specified drive letter from a volume, partition, or logical drive on the server. This is a synchronous task.

 HRESULT FreeDriveLetter(
   [in] wchar_t letter,
   [in] unsigned long forceOption,
   [in] hyper letterLastKnownState,
   [in] LdmObjectId storageId,
   [in] hyper storageLastKnownState,
   [out] TASK_INFO* tinfo
 );

letter: Drive letter to free.

forceOption: Boolean value that indicates whether to force the freeing of a drive letter.

Value

Meaning

NO_FORCE_OPERATION

0x00000000

If the specified drive letter is assigned to a volume, partition, or logical disk that is in use, contains the paging file, or contains the system directory, the operation fails and returns an error.

FORCE_OPERATION

0x00000001

The specified drive letter is always freed.

letterLastKnownState: Drive letter's last known modification sequence number.

storageId: Specifies the object identifier of the volume, partition, or logical drive to which the letter is assigned.

storageLastKnownState: Last known modification sequence number of the volume, partition, or logical drive to which the drive letter is assigned.

tinfo: Pointer to a TASK_INFO structure that the client uses to track the request's progress.

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:

  1. Verify that the drive letter specified by letter is in the list of storage objects, and check whether letterLastKnownState matches the LastKnownState field of the object.

  2. Verify that the volume, partition, or logical drive specified by storageId is in the list of storage objects, and check whether storageLastKnownState matches the LastKnownState field of the object.

  3. Verify that the drive letter specified by letter is associated with the volume, partition, or logical drive specified by storageId.

  4. Verify that tinfo is 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 process the message as follows:

  1. Attempt to remove the drive letter specified by letter from the storage object specified by storageId.

  2. The behavior of the drive letter removal for volumes, partitions, or logical drives that are in use, contain the paging file, or contain the system directory is controlled by the parameter forceOption:<79>

    • If the parameter is set to NO_FORCE_OPERATION, the removal fails.

    • If the parameter is set to FORCE_OPERATION, the removal succeeds.

  3. Wait for the drive letter removal to either succeed or fail.

  4. Fill in the tinfo output parameter.

    TASK_INFO member

    Required for this operation

    TASK_INFO::id

    Required.

    TASK_INFO::storageId

    Not required.

    TASK_INFO::createTime

    Not required.<80>

    TASK_INFO::clientID

    Not required.<81>

    TASK_INFO::percentComplete

    Required for any task that returns REQ_IN_PROGRESS.

    TASK_INFO::status

    Required.

    TASK_INFO::type

    Required if PercentageComplete is being used.

    TASK_INFO::error

    Required.

    TASK_INFO::tflag

    Not required.<82>

  5. Return a response to the client that contains tinfo and the status of the operation.

If the operation is successful, the server MUST make the following change to the list of storage objects before returning the response:

  • Modify the object that corresponds to the drive letter to mark it as free.