A Roadmap to the Recently Released Windows APIs
Pages: 1, 2

5. Interface IActiveDesktopP

interface IActiveDesktopP : public IUnknown {
	// IActiveDesktopP methods
	STDMETHOD SetSafeMode(DWORD dwFlags);
	STDMETHOD EnsureUpdateHTML();
	STDMETHOD SetScheme(LPCWSTR pwszSchemeName,
	    DWORD dwFlags);
	STDMETHOD GetScheme(LPWSTR pwszSchemeName,
	    DWORD *lpdwcchBuffer, DWORD dwFlags);
};

'Safe Mode', in this case, appears to lock the Active Desktop from changes. The documentation describes only the SetSafeMode method of IactiveDesktop and implies that there is no way to un-set Safe Mode, although the header file adds flags like SSM_CLEAR and SSM_REFRESH.

For more information, click here.

4. Interfaces INamespaceWalk and INamespaceWalkCB

interface INamespaceWalkCB : public IUnknown {
    // INamespaceWalk methods
    STDMETHOD Walk(IUnknown *punkToWalk,
        DWORD dwFlags, int cDepth, INamespaceWalkCB *pnswcb);
    STDMETHOD GetIDArrayResult(UINT *pcItems, LPITEMIDLIST **pppidl);
};

interface INamespaceWalkCB : public IUnknown {
    // INamespaceWalkCB methods
    STDMETHOD FoundItem(IShellFolder *psf, LPCITEMIDLIST pidl);
    STDMETHOD EnterFolder(IShellFolder *psf, LPCITEMIDLIST pidl);
    STDMETHOD LeaveFolder(IShellFolder *psf, LPCITEMIDLIST pidl);
    STDMETHOD InitializeProgressDialog(LPWSTR *ppszTitle, LPWSTR
*ppszCancel);
};

This pair of interfaces is used to walk a namespace from a specified root node. If you specify the desktop's IShellFolder as the root, it allows the possibility of walking the entire Windows namespace. To use this functionality, you create an object that implements the INamespaceWalkCB interface. Windows implements the actual namespace walker, which can be gotten by calling CoCreateInstance with a CLSID of CLSID_NamespaceWalker. Just pass in a pointer to your callback object, and wait for the notifications to come.

For more information, click here.

3. Function SHCreateStdEnumFmtEtc

With the release of the August 2002 SDK Update, the shell now contains probably every COM helper function you ever wished Microsoft would provide, but were too lazy to write yourself. SHCreateStdEnumFmtEtc is an especially useful function that takes an array of FORMATETC structures and returns an IEnumFORMATETC pointer. IEnumFORMATETC must be implemented by all data objects to support calls to IDataObject::EnumFormatEtc.

For more information, click here.

2. Functions ReadCabinetState and WriteCabinetState

BOOL ReadCabinetState(CABINETSTATE* lpState, int cbLength);
BOOL WriteCabinetState(CABINETSTATE* lpState);

typedef struct {
     WORD cLength;
     WORD nVersion;
     BOOL fFullPathTitle:1;
     BOOL fSaveLocalView:1;
     BOOL fNotShell:1;
     BOOL fSimpleDefault:1;
     BOOL fDontShowDescBar:1;
     BOOL fNewWindowMode:1;
     BOOL fShowCompColor:1;
     BOOL fDontPrettyNames:1;
     BOOL fAdminsCreateCommonGroups:1;
     UINT fUnusedFlags:7;
     UINT fMenuEnumFilter;
} CABINETSTATE;

These functions work with the newly documented CABINETSTATE structure to update some of the global "Folder Options" for the shell.

For more information, click here.

1. Function CheckNameLegalDOS8Dot3

A function to check the format of a DOS 8.3 filename, and newly added in Windows XP, seems an ironic addition to an operating system said to mark the final demise of DOS.

For more information, click here.

State of the Documentation

Once you've looked at a certain amount of Microsoft documentation, differences in formatting really begin to stand out. To the knowledgeable programmer, the "vintage" of a particular entry or section is clearly identifiable by the style in which it is formatted, and most of the new Platform SDK entries share a common formatting template. One of the most obvious characteristics of this template is that there is no longer any mention of the Windows 9x series, although many of the functions that are only now being documented were first present in Windows 95. And yet the "Minimum operating systems" entry for these functions reads "Windows 2000". Microsoft says that since coverage of releases prior to Windows 2000 is not required by the consent decree it chose to go for breadth over depth.

For more information, click reference here.

Here are some other surprises we encountered during our initial foray into the SDK:

• Missing Information. Henk Devos claims at http://www.theregister.co.uk/content/4/26803.html to have discovered two new interfaces, IDelegateFolder and IBrowserFrameOptions in the SDK, but neither is included in the SDK documentation. Microsoft says documentation of these interfaces isn't required by the consent decree, but wouldn't rule out documenting them later. That answer won't satisfy those looking for more insight into what appear to be IE hooks into the operating system.
• Flawed Information. We've already noted that the "Minimum operating system" specified for a function is often incomplete in the SDK documentation. We've also found that better information can sometimes be found elsewhere. SHFormatDrive, for instance, is more accurately and more completely documented by Microsoft itself at http://support.microsoft.com/default.aspx?scid=KB;EN-US;q173688& We found the SDK entry for DSA_Create to be subtly wrong, and the difference between Dynamic Structure Arrays and Dynamic Pointer Arrays was not clear to us until we found better documentation at http://www.geocities.com/SiliconValley/4942/arrays.html
• Obsolete Interfaces. Some functions are clearly marked as going away in a future version, so be very sure of what you're getting yourself into before using them. RegisterShellHookWindow and IsHungAppWindow are in this category, among others.
• Alternate Functions. Some of the functions have recommended alternatives. CertGetNameString should be used with the CERT_NAME_FRIENDLY_DISPLAY_TYPE flag instead of calling GetFriendlyNameOfCert directly.
• Incomplete Entries. As an example of an incomplete topic, the entry for ITargetFrame doesn't have information about how the interface is used or which objects implement it. Eight of the fourteen methods are listed as "Not currently implemented."

Conclusion

Otto von Bismarck said it best, "If you like laws and sausages, you should never watch either one being made." Ironically, it's the law that has determined that Microsoft must reveal just a bit more about how they make their own sausages than anyone else. As a chef that uses a lot of Microsoft sausage in my own recipes, I appreciate having as much insight as I can get into how they're made. I may well decide to avoid the obsolete sausages in favor of the more stable, well-known, and well-supported sausages, but I feel much better having the choice.

References

• Undocumented Windows 95 Dynamic Array Routines
• Namespace extensions: the undocumented Windows Shell
• Namespace Extensions: the IDelegateFolder mystery

Curt Hagenlocher is responsible for research and development at Motek, Inc., and has over 20 years of programming experience.

Chris Sells is a Microsoft Software Legend and a Program Manager with the Distributed Systems Group at Microsoft. His weblog at http://www.sellsbrothers.com is popular with .NET developers for its zany and independent commentary on technology and geek culture.

---

Return to .NET DevCenter