oreilly.comSafari Books Online.Conferences.


AddThis Social Bookmark Button

A Roadmap to the Recently Released Windows APIs

by Curt Hagenlocher and Chris Sells

There is a common belief among programmers--particularly those disinclined to believe the truth of anything coming out of Redmond--that Windows is full of "secret functions." These functions, so the story goes, are used by Microsoft to prevent independent reimplementation of its operating system and to give its own applications programmers an extra advantage. With the August 2002 release of its Platform SDK, Microsoft is complying with the terms of the consent decree it signed with the Department of Justice in November 2001. The decree requires Microsoft to document those interfaces that were previously regarded as "internal" and are called by specific Microsoft products such as IE and Media Player to obtain services from the Microsoft® Windows® 2000 and Windows XP desktop client operating systems. If you are one of the people who harbor suspicions against Microsoft, then you're not likely to be convinced that the recent release has changed anything. For a lot of the rest of us, including shell integration programmers, cryptographers, and the terminally curious, the new information is fascinating and potentially useful, although not always as complete as we'd like.

For a complete list of the August 2002 Platform SDK interfaces released as part of the consent decree, click here.

What's New?

To begin with, the list of nearly 300 new entries in the index contains not only functions, but also COM interfaces, constants, registry key values and overviews. The header files and import libraries have also been updated with the new items. The new information for CryptoAPI and Multimedia seems particularly well done, while information regarding the shell functions is, from our perspective, often undercooked.

The new Platform information falls into roughly four categories: the shell, the CryptoAPI, Multimedia, and the runtime library (RTL).

Category 1: The Shell

The newly documented shell functions form a large category that includes functions directly related to the Windows Explorer's business, as well as utility and helper functions. Interested individuals and groups outside of Microsoft have documented many of these items before. As such, the main effect of including them as part of the Platform SDK is likely to be their implicit "blessing" by Microsoft for widespread use or, in certain cases, a clear warning of possible future deprecation.

The single most important group of functions to have been documented are those that support the default shell folder view object. This is an object that is created using the SHCreateShellFolderView and SHCreateShellFolderViewEx functions. By passing a pointer to your own IShellFolder implementation and a pointer to a callback function, you can get Windows to do the dirty work of creating both the actual window and implementing some closely related interfaces like IShellView. The window will automatically handle painful tasks like changing the toolbar and switching between "Large Icons" and "Small Icons". Microsoft itself makes fairly extensive use of these functions.

Related Reading

.NET Framework Essentials
By Thuan L. Thai, Hoang Lam

The internal shell icon cache has now been documented as well. Windows uses this cache to store all the images it needs to draw the desktop and all open folders. By storing them all in one place, the operating system doesn't have to keep opening each individual file just to extract the appropriate icon.

The SDK includes helper functions for a variety of other shell integration tasks as well, including drag and drop, handling variable-sized arrays of pointers and structures, pathname and ITEMIDLIST manipulation. There are also property sheet utilities that are useful for implementing your own shell views.

To get started with the default shell view, look at SHCreateShellFolderView. Then, go to for a more thorough look at the same information. For drag and drop helpers, start with DAD_AutoScroll. For the shell icon cache, look at IShellImageStore. For property sheets, try SHOpenPropSheetW.

Category 2: Crypto Functions

Many of the cryptography functions that were added to the August Platform SDK release could be "altered or unavailable in subsequent versions", according to the documentation. In some cases, the SDK documentation suggests use of another function that achieves the same result. Nevertheless, information on the internal functions whose future is uncertain is still useful to those of you interested in Windows security, because of the visibility it provides to the internals thereof. There is one set of newly documented internal crypto functions worth your attention for which no alternative is suggested: APIs for administering the cryptography catalog.

For a glimpse at Security internals, try looking at WTHelperGetProvSignerFromChain or WintrustLoadFunctionPointers. For new XP functionality, look at CredUIReadSSOCredW. For administration of the cryptography catalog, start with CryptCATAdminAddCatalog.

Category 3: Multimedia

The newly published multimedia APIs are quite well documented. Much of information provided describes the architecture of source filters under Windows Media Player 6.4. While these filters are described as "legacy", the help entry goes on to declare that these are still the default source filters used in the playback of .wma, .wmv and .asf files. However, more recent multimedia information can be found in the documentation for the DirectX APIs.

To dig into the new multimedia information, start at the documentation for "Windows Media Source Filter"

Category 4: RTL

The language-independent runtime library (RTL) functions are low-level services provided by the operating system to compilers for use in the compiled output. Because these are low-level, there is usually no language-specific runtime library that would bother wrapping them. RTL functions are rarely used by programmers directly, but are instead intended to be used in code generated by compilers. The newly-documented functions include simple string and memory operations, as well as RtlUnwind which is used for exception handling. Most can be easily recognized by the prefix "Rtl". Unless you're writing a compiler, you aren't likely to need these functions.

Top Ten Previously Undocumented Things

Here is a list of cool, useful, and funny things you'll find in the August 2002 SDK update. Each has previously been considered "internal" by Microsoft, and could still disappear in future versions of Windows.

10. Function PerUserInit

void PerUserInit(); 

The PerUserInit function sets up "My Documents" and performs other per-user initialization the first time a specific user logs into a specific computer. But, as the documentation says, "Applications do not need to call this function because the OS already does so."

For more information, click here.

9. The Shell Folder Band Object

The documentation tells us that the Quick Launch Bar is an example of a folder band. It also says that the Shell Folder Band object has a CLSID of CLSID_ISFB and, implements the IShellFolderBand interface and is used to manage your folder band collection. It does not, unfortunately, tell us how to use the ShellFolderBand object to do any of these things.

For more information, click here.

8. Function AsyncInstallDistributionUnit

HRESULT AsyncInstallDistributionUnit(
	LPCWSTR szDistUnit,
	DWORD dwFileVersionMS,
	DWORD dwFileVersionLS,
	IBindCtx* pbc,
	LPVOID pvReserved,
	DWORD flags

We're not entirely sure what this function does or how it's used, and the documentation certainly doesn't say, but our guess is that it's used to download and install handlers for particular types of MIME data. AsyncInstallDistributionUnit is implemented on every version of Windows starting with Windows 95 and including Windows CE, so whatever it does, it seems to be fairly popular.

For more information, click here.

7. Function PathIsSlow

BOOL PathIsSlow(LPCTSTR pszFile, LPCTSTR pszIconPath);

The PathIsSlow function returns TRUE if the file passed as the first argument is on a high-latency network connection. Before opening a file, you can first call this function and then, when TRUE, ask the user if he's really, really sure he wants to open that 4 MB file over a 28.8 Kbps line.

For more information, click here.

6. Interface IInsertItem

interface IInsertItem : public IUnknown {
	// IInsertItem methods

It's hard to imagine a more abstract interface than this. A single method serves to insert an ITEMIDLIST into an arbitrary list. Even the new documentation fails to specify which objects implement this interface, but it's not hard to guess that IInsertItem has something to do with iterating over the contents of a shell folder.

For more information, click here.

Pages: 1, 2

Next Pagearrow