IVolumeClient4::GetVolumeDeviceName (Opnum 4)

The GetVolumeDeviceName method retrieves the Windows NT operating system device name of a dynamic volume on the server.

 HRESULT GetVolumeDeviceName(
   [in] LdmObjectId _volumeId,
   [out] unsigned long* cchVolumeDevice,
   [out, size_is(,*cchVolumeDevice)] 
     WCHAR** pwszVolumeDevice

_volumeId: Specifies the OID of the volume whose path name is being returned.

cchVolumeDevice: Number of characters returned in pwszVolumeDevice, including the terminating null character.

pwszVolumeDevice: Pointer to a null-terminated array of characters that stores the Windows NT device name of the volume specified by volumeId. The device name is in the format \Device\DeviceName. Memory for the array is allocated by the server and freed by the client.

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]; 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 cchVolumeDevice and pwszVolumeDevice are not NULL.

  2. Verify that the dynamic volume specified by volumeId is in the list of storage objects.

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 compose a response to the client as follows:

  1. Retrieve the device name of the dynamic volume specified by volumeId. The device name is an OS-specific name that can be used to access the device from the kernel.

  2. Allocate a buffer large enough to contain the device name, including the terminating null character.

  3. Populate the buffer with the device name, including the terminating null character.

  4. The buffer MUST be returned to the client in the output parameter pwszVolumeDevice.

  5. The number of characters in the buffer, including the terminating null character, MUST be returned in the output parameter cchVolumeDevice.

  6. Return a response that contains the preceding output parameters and the status of the operation.

The server MUST NOT change the list of storage objects as part of processing this message.