Geoff Chappell - Software Analyst
Please bear in mind the following points throughout this Study of the Windows Shell.
The work presented here is for my practical necessity tied to particular editions of both the documentation and the software. This study is the work of one person, performed in time snatched between items of paid work—indeed, rather too often instead of accepting paid work. Were every resumption to require consultation of the latest documentation from Microsoft just in the hope of catching what has changed, then the work would never advance far enough to have been worth starting.
If you seek more comprehensiveness or authoritativeness than I provide, then wonder why you can’t rely on getting it from Microsoft, or why it isn’t delivered through the mechanics of competition in a free market, or why governments haven’t seen to it for the protection of consumers or even for the credibility of their own legal processes.
Except where otherwise noted, the reference version when citing Microsoft’s documentation is the Windows Vista Software Development Kit (SDK), as supplied on MSDN Disc 3667 and dated January 2007. It seems as closely contemporaneous as possible to the retail release of Windows Vista, and has the merit of neatness (in beginning a calendar year).
Another reference that is sometimes used, especially in pages that were written early in the study and have not been updated, is the CD edition of the MSDN Library dated January 2004. There is no particular reason for this choice other than its being the most recent edition I had to hand when I first started thinking of this study as something I might want to work at seriously.
At the time, I could only plead the following as my justification for persisting with reference documentation that would surely be stale by the time I have anything to show from this study:
Consider that some of the functions and other interface features described here have histories reaching as far back as 1995 (Windows 95) or 1996 (NT 4.0), and most as far back as 1997 (Internet Explorer 4.0) or 1999 (Internet Explorer 5.0 and Windows 2000). If these are still not documented by their manufacturer as late as January 2004, then the wonder ought not be that one man doesn’t keep right up to date: instead, wonder at how one of the richest commercial ventures that the world has ever seen can be so tardy.
With the passing of time, however, the choice of documentation from 2004 has turned out to have value as a snapshot of how things stood after Microsoft’s documentation of Settlement Program Interfaces, dated December 2002. The naive might think this settlement documentation to have been thorough. The less naive might think it would be checked independently and authoritatively through enforcement mechanisms built into the settlement.
In the years since Microsoft’s initial announcement about compliance with the settlement, and since the initial tranche of newly documented functions, there has been at Microsoft a quiet programme of documenting yet more shell functions, and even appreciably many more. There seems never to be an announcement, let alone an explanation, e.g., of whether any of these newly documented functions ought to have been caught for the settlement and are now offered with Microsoft’s apologies. For rather too many of these functions, including ones that are more than a decade old, the documentation lists Windows Vista as a minimum requirement or is prefaced by a bold red warning about being pre-release and subject to change. A reader unfamiliar with the history might easily infer that these functions actually are new, not just to the documentation, but to the software. Though this effect might not actually have been intended by Microsoft, it can’t possibly have been unforeseen.
The reference version for any discussion of implementation details in any function—or of interface properties, given that these must in some cases be inferred from implementation details—is whatever build was distributed with Windows XP SP1, as supplied on MSDN disc 1847.1, dated July 2003. Again, there is no particular reason for this choice other than its being the most recent edition I had to hand when I began the study. However, this choice of reference edition is especially apt for an examination of Microsoft’s compliance with the settlement’s requirements for API disclosure: Windows XP Service Pack 1 is cited explicitly in the Final Judgment (Section III.D) as being at least the first edition by which compliance must be demonstrable.
Articles written more recently tend to describe the behaviour of Windows Vista. Depending on my interest, I may have tracked down variations for earlier versions. Where I have not, and I have not thought to specify which version the page currently describes, then for a reliable guide, look for the summary of documentation status, and failing that for when the page was created.
If the reference documentation is the January 2004 edition of the MSDN Library on CD, then the article describes the implementation in Windows XP SP1. If the reference documentation is the January 2007 edition of the Windows Vista SDK, then the article describes the implementation in Windows Vista.
If no reference documentation is cited, then look at the date the page was created. If the page was created before 2007, then the article describes the implementation in Windows XP SP1. If the page was created in 2007 or later, then the reference version for the software is the original Windows Vista.
For each shell module that is yet surveyed, there is a master list of all functions that appear in that module’s export directory in any known retail release. This master list is reached by clicking the heading Functions one level beneath the name of the module in the table of contents.
The master list shows for each function just a summary of its applicable versions and documentation status. A number in parentheses after a function’s name means that at least some version has this function exported only by ordinal, and the number (of course) is that ordinal.
Throughout the study, but especially for tracking the history of a module’s functional interface, I have found it useful to separate those functions that are exported by name from those that are exported only by ordinal. The latter are less accessible, partly by their nature in programming but even more by Microsoft’s practice. As a set, therefore, they make fertile ground for finding functions that Microsoft has kept for private use. Most of the functions that are exported only by ordinal are undocumented. Most of the functions that Microsoft does not document are exported only by ordinal.
Some few functions link from the master list to a page of alternative documentation. For all others, the most elaboration will be found by looking for the function in the section headed Versions. Again, this section is one level beneath the module’s name in the table of contents.
Each function appears within the history under its version of first appearance, in a list either of named exports or ordinal-only exports. Among the elaborations to be found here are:
The history is of course surmised from inspection of known versions. Beware that “known” means that I found copies on old disks, mostly from occasional MSDN subscriptions. Pre-release and debug builds are avoided entirely. My collection is far from complete and anyway does not extend further back into time than 1995, when I, like much of the world, had my first exposure to 32-bit user-mode Windows. For each module in the survey, the versions that I have found and studied are listed on the index page of that module’s section headed Versions. A few service packs are missing, and although I have updated the survey as far as Windows Vista, I have not troubled to obtain a copy of Internet Explorer 7.0 (which apparently is not shipped on disc with MSDN subscriptions).
A colour-coding scheme has developed for lists of functions where the documentation status is not the focus of attention, e.g., with its own column in the table, but is nonetheless of some interest.
Functions that were documented explicitly for the settlement are shaded red. Functions for which I did not find documentation in the January 2004 edition of the MSDN Library on CD, i.e., over a year later, are highlighted yellow, except that if I notice that Microsoft has documented them subsequently, they are merely shaded yellow. If in doubt, and scripting is enabled, hover the mouse cursor over the function’s name and read the tooltip. (Throughout this study, any in-line text that is bold, italic, coloured or in any way different from the surrounding text should have a tooltip to explain why.)
Please keep in mind that some functions get documented under headings that hardly cry out their connection to the module in which the function is implemented. That a function is marked as undocumented does not mean for certain that Microsoft does not document it, just that I haven’t found where.
Some functions that are exported by name are never formally documented, at least not specifically for any one module. It would be ungenerous to count these as undocumented, but it would be tiresome to explain every time they occur in the wider survey. The theme is that these exceptions are not ordinarily thought of as API functions. As some measure of this, note that where a module does export functions in the following cases, it would be plausibly a common practice (and certainly a recommendable practice) to arrange that the names not appear in the import library for that module.
Any module that aims to satisfy, or at least to conform better to, the documented expectations of the Component Object Model (COM) may export functions named DllCanUnloadNow, DllGetClassObject, DllRegisterServer and DllUnregisterServer. Something similar, though for a different purpose, applies to functions named DllGetVersion and DllInstall. Microsoft documents each of these functions generally. There is no point to re-documenting them specifically for each module that actually does export any of them.
Something similar might be true eventually of the function named RegisterClassNameW. It may be usefully exported by any module whose assembly manifest names a window class. However, Microsoft does not document it, generally or not, and this survey therefore lists its implementation in COMCTL32 as an undocumented export.
Functions whose names contain RunDLL are typically intended as calling points for the RUNDLL32 utility, with the name of the function being specified on the RUNDLL32 command line. For programming purposes, though arguably not for the usability purpose of knowing what arguments should follow on the command line, they can be documented collectively by noting what RUNDLL32 expects of any of them.
Names that end in ThunkData32 typically exist to help with calling a 32-bit module from a 16-bit companion. They are constructed to a pattern that satisfies the thunk compiler (and are, incidentally, for data, not for functions). They are not usefully documented for that 32-bit module specifically. Microsoft does anyway document the thunk compiler, at least for usability, if not for the run-time expectations of the thunk code.
The name WIN32SYSDLL is exported from all Win32s executables.
The software described for this study is intended to run on either or both of two operating systems. It may be that the one executable runs on both, but more often the executable exists in two implementations, one for each system. A difficulty of nomenclature arises because Microsoft uses the name Windows for both systems, with good reason at the higher levels, but with some risk of confusion at the lower levels such as dealt with here. (As background, note that this talk of the shell as a lower level is highly relative. As a specialist in disk and file I/O, as for kernel-mode device drivers, this study of the Windows shell is about as high-level as I ever get.)
The general term NT is meant throughout to apply to the succession Windows NT 3.51, Windows NT 4.0, Windows 2000, Windows XP, Windows 2003 Server, Windows Vista and apparently all 32-bit Windows releases in the imaginable future.
The general term Windows, usually in opposition to the term NT, is reserved here for those releases that boot from the MS-DOS operating system, whatever has been said to the contrary by various representatives of Microsoft, even under oath. These systems are specifically Windows 95, Windows 98 and Windows Me.
In any count of functions, and in many lists, my aim is that ANSI and Unicode forms identified by an A or W suffix do not count as distinct. If there exists a third form without a suffix, it too does not count as distinct. Omitting the suffix both when writing of a function and when using it in program code is a long-standing and convenient practice both in Microsoft’s documentation and in relevant header files from the various development kits for user-mode Windows programming (whether called Win32 SDK, Platform SDK, Windows Vista SDK, etc).
Where function prototypes omit the calling convention, assume __stdcall. Also assume C linkage, unless otherwise noted or plainly implied (e.g., by use of C++ syntax).