Dynamic Structure Arrays

From the very start, with version 4.00, COMCTL32 provided a set of functions for working with arrays of fixed-size structures. Apart from the addition of two functions in version 4.71, the interface was stable until a catch-up (with similar DPA functions) for Windows Vista:

Documentation Status

Though 8 of the 13 DSA functions date from the original Windows 95 and two from Internet Explorer 4.0 (released in 1997), none were documented until late 2002 as Settlement Program Interfaces. Even then, Microsoft documented only half as many as existed, and declared these as requiring Windows 2000 as the minimum operating system.

As with much of the documentation that results from that settlement, Microsoft’s effort is extraordinarily grudging and miserly. This documentation comes with no overview of the functionality. Barely all that is offered is that for each function, such little information as a competent reader might discern from uncommented C-language prototypes is repackaged in the standard form of MSDN documentation. The C-language prototypes anyway do not seem to have been released (in COMMCTRL.H, as supplied with the Platform SDK) until 2003.

For compliance with Section III.D of the Final Judgment in a well-publicised anti-trust suit by various U.S. governments, Microsoft must document all API functions that are implemented in components of Windows and used by components of so-called Microsoft Middleware and particularly of Internet Explorer. Of the 10 pre-Vista DSA functions, 9 are used by SHDOCVW.DLL, i.e., by the essence of Internet Explorer. Only one (DSA_EnumCallback) is plausibly an internal Windows API, whose only known use is by other components of Windows (specifically by EXPLORER.EXE and SHELL32.DLL) and not by any components of anything that the judgement defines as a Microsoft Middleware Product. How can it be that only 5 got documented for the settlement?

Post-Settlement Documentation

Some time during 2006 (but perhaps in 2005), Microsoft documented three more DSA functions: DSA_DeleteItem, DSA_GetItem and DSA_SetItem. These newly documented functions are acknowledged as dating from Windows 95, not that it seems to have occurred to anyone to wonder at how these functions might then have obtained their expected DSA handle when no function that can produce a DSA handle would be available for another few years. Personally, I can only applaud the sense of humour of whoever at Microsoft saw that these functions are a decade old yet added the same bright-red tag “This documentation is preliminary and is subject to change” that Microsoft more typically uses for interfaces that are still in development.

That warning got removed in time for the Windows Vista SDK dated January 2007, which also documents the two remaining old DSA functions and the three new ones.