3.2.4.4.1.19 IVolumeClient::AssignDriveLetter (Opnum 22)

The AssignDriveLetter method assigns the specified drive letter to a volume, partition, or logical drive. This is a synchronous task.

 HRESULT AssignDriveLetter(
   [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 assign.

forceOption: Value that indicates if drive letter assignment is forced when it fails.

Value	Meaning
NO_FORCE_OPERATION 0x00000000	If the volume, partition, or logical drive specified by storageId cannot be locked, the operation fails with LDM_E_VOLUME_IN_USE.
FORCE_OPERATION 0x00000001	If the volume, partition, or logical drive specified by storageId cannot be locked, the server will proceed with the operation.

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

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

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

tinfo: Pointer to a TASK_INFO structure that the client can use 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 the 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 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. Convert the letter parameter to uppercase.

2. Attempt to lock the file system (if this is applicable). Locking the file system prevents any other threads from accessing the volume.

3. If the attempt to lock the file system fails, and the NO_FORCE_OPERATION flag was input, the server MUST fail the operation. If the attempt to lock the file system fails, and the FORCE_OPERATION flag was input, ignore the lock failure and continue.

4. Delete any existing drive letter path name associated with the volume. If the existing drive letter path name cannot be deleted, the server MUST fail the call.

5. Assign the drive letter to the storage object.

6. Wait for the drive letter assignment to either succeed or fail.

7. 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.<76>
   TASK_INFO::clientID	Not required.<77>
   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.<78>

8. 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 changes to the list of storage objects before returning the response:

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

• Modify the object that corresponds to the letter to mark it as associated with the storage object.