PathGetDriveNumber

This function parses a path for its drive component.

Declaration

int PathGetDriveNumber (LPCTSTR lpsz);

The function exists in ANSI and Unicode forms.

Parameters

The lpsz argument provides the address of a drive specifier.

Return Value

The function returns the 0-based drive number, else -1.

Behaviour

The function fails, i.e., returns -1, if lpsz is NULL or the first character at lpsz is null.

In the Unicode form only, if the characters at lpsz begin as two backslashes, a question mark and another backslash, the function ignores these four characters.

A drive specifier is a drive letter and a colon. The function fails if the first character is not a drive letter in upper or lower case, or if the second character is not a colon. Otherwise, the function returns a 0-based drive number, as in 0 for drive A, 1 for drive B, etc.

Variations

The preceding description is for the version 6.0 from Windows Vista. The following variations are known for earlier versions.

Versions before 5.00 simply assume that lpsz is not NULL.

Ignoring a leading \\?\ is new for Windows Vista. So is the explicit defence against the first character being null.

Availability

The PathGetDriveNumber function is exported by name (with ANSI and Unicode suffixes) from SHLWAPI in version 4.70 and higher. It is also exported from SHELL32.DLL as ordinal 57 (in ANSI for Windows builds and Unicode for NT builds) in version 4.0 and higher. The implementation in SHELL32 version 5.0 and higher is just to dump to the coding in SHLWAPI.

This function has been documented since some time in 1997-98. Though it dates from 1996 in SHLWAPI and from 1995 elsewhere, it has always been said to require at least SHLWAPI version 4.71.

Microsoft’s documentation hints only vaguely at this function ignoring anything (let alone \\?\ particularly) before the drive specifier.