GetVolumePathNamesForVolumeName function
Applies to: desktop apps only
Retrieves a list of drive letters and mounted folder paths for the specified volume.
Syntax
BOOL WINAPI GetVolumePathNamesForVolumeName( __in LPCTSTR lpszVolumeName, __out LPTSTR lpszVolumePathNames, __in DWORD cchBufferLength, __out PDWORD lpcchReturnLength );
Parameters
- lpszVolumeName [in]
-
A volume GUID path for the volume. A volume GUID path is of the form "\\?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\".
- lpszVolumePathNames [out]
-
A pointer to a buffer that receives the list of drive letters and mounted folder paths. The list is an array of null-terminated strings terminated by an additional NULL character. If the buffer is not large enough to hold the complete list, the buffer holds as much of the list as possible.
- cchBufferLength [in]
-
The length of the lpszVolumePathNames buffer, in TCHARs, including all NULL characters.
- lpcchReturnLength [out]
-
If the call is successful, this parameter is the number of TCHARs copied to the lpszVolumePathNames buffer. Otherwise, this parameter is the size of the buffer required to hold the complete list, in TCHARs.
Return value
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError. If the buffer is not large enough to hold the complete list, the error code is ERROR_MORE_DATA and the lpcchReturnLength parameter receives the required buffer size.
Examples
For an example, see Displaying Volume Paths.
Requirements
|
Minimum supported client | Windows XP |
|---|---|
|
Minimum supported server | Windows Server 2003 |
|
Header |
|
|
Library |
|
|
DLL |
|
|
Unicode and ANSI names | GetVolumePathNamesForVolumeNameW (Unicode) and GetVolumePathNamesForVolumeNameA (ANSI) |
See also
Send comments about this topic to Microsoft
Build date: 4/17/2012
By most calculations this should 3 or 6.
Now this results in behaviour I want as I do not want the trailing backslash as I truncate after 2 characters but was a surprise and I am not sure what will happen with multiple partitions on a volume (as do not have this set up on development unit).
- 6/14/2011
- ballboy54
This function seems to have a bug when reporting the size of the required buffer. When I call it to determine the required buffer size, it reports that I need 5 bytes for the path name ("D:\" + NULL + NULL), which is correct. I allocate the buffer and make the call again. It succeeds and has the correct information in the buffer. When I try to free the buffer, I get a heap corrupted exception. I have not manipulated the buffer or pointer. In my example, if I allocate 10 bytes (2*requiredlength), everything is okay. If I allocate 9 bytes, it fails. This seems to indicate that the UNICODE version of this function is not returning the correct number of bytes, which would be ANSI size * 2. As a work-around, I am doubling the length it returns and all is well.
LPTSTR buf = NULL;
DWORD rlen = 0;
GetVolumePathNamesForVolumeNameW(volumeName, buf, 0, &rlen);
if (GetLastError() == ERROR_MORE_DATA)
{
buf = (LPTSTR) malloc (rlen*2);
.
The functions works correct!
Regarding the API documentaion the number of characters is returned and NOT the number of bytes! So in case of UNICODE you get 5 characters including the null terminator back. So for UNICODE you have to allocate 5*sizeof(WCHAR)=10 bytes.
.
If you set lpcchReturnLength to zero the value will not be modified even GetVolumePathNamesForVolumeName() returns ERROR_MORE_DATA.
The sample code leads to an infinite loop in that case :-((
Problem seen on Windows XP, Windows Server 2008 x64. I'm sure it exists on other Windows versions too.
The UNICODE version returns a character count. See also other community comments on returned buffer size.
