Geoff Chappell - Software Analyst
The first released version of SHLWAPI, namely 4.70, exported numerous functions for working with paths and pathnames and for operating on the corresponding files and directories. Many are very much the sorts of things that programmers find themselves writing too often and spending too much time over because of surprisingly many special cases. As Matt Pietrek said in A Programmer’s Perspective on New System DLL Features in Windows NT 5.0, Part II, apparently from Microsoft Systems Journal in December 1997, this is “useful ‘Why didn’t they do this three years ago?’ functionality” to do “potentially error-prone work for you”.
As it happens, at least a few of these functions for path manipulation were already old (for an industry with notoriously short attention). They were just not known very widely. SHLWAPI version 4.70 was already in retail releases of Windows over a year earlier. Moreover, some of the functions had an even earlier life, dating from the original Windows 95, but implemented in SHELL32. I do not mean to put words in Matt’s mouth, but I wonder if as a co-author of Undocumented Windows (Addison-Wesley, 1992, ISBN 0-201-60834-0), his question was really code for “Why didn’t they document this three years ago?”
The following list shows the path utility functions that are exported from SHLWAPI version 6.00.2800.1106 (Windows XP Service Pack 1). A version in brackets is the first SHLWAPI version that is known to export the function. Where no version is given, it is understood that the function dates from SHLWAPI version 4.70 (released in 1996), or earlier. Most, by far, are indeed that old. The truly ancient functions that SHLWAPI acquired from SHELL32 version 4.0 are shaded blue.
A handful of path utility functions were added for version 4.71, which is when Microsoft got round to documenting the set. Note that almost all the path utility functions are documented. However, it is conspicuous that among the continuing additions almost all that have been added since Windows 2000 are undocumented. Functions that were not documented as late as the January 2004 edition of the MSDN Library on CD are highlighted yellow.
It is in the nature of working with paths that these functions almost all have ANSI and Unicode forms. The only exceptions are PathSkipLeadingSlashesA and PathFileExistsDefExtAndAttributesW. The functions chosen as path utilities for the purpose of this article are all those that SHLWAPI acquires from object files named PATHA.OBJ and PATHW.OBJ, linked from libraries SHLWANSI.LIB and SHLWUNI.LIB respectively. The ANSI and Unicode implementations are each native to their character sets, as opposed to one converting to and from the other. They seem likely to differ only through conditional compilation.