There have long been complaints about undocumented functions in the Windows API which give Microsoft’s internal developers an advantage over third-party software developers. Perhaps even more frustrating are those that are semi-documented. An example was found recently by a user of the htmleditor, a .NET wrapper for the HTML editor built into Internet Explorer. If you write an editor you might want to support undo and redo; there are simple undo and redo commands available but they are crude. The API also provides more advanced functions, including a change log and the ability to undo or redo entries in the log. You can find the documentation here; the relevant interfaces are IHTMLChangeLog, IHTMLChangePlayback and IHTMLChangeSink.

All looks good on a brief inspection; but note the lack of any sample code. Then think about how you might want to use this API. What exactly does an item in the change log represent – a single character, an HTML element, a paste operation, or what? How can you inspect the items (they seem to be a binary black box, understood only by an API function called ExecChange)? There is only one function for iterating through a change log, called GetNextChange – are you intended to cache the entries somewhere, since there is no GetPreviousChange or GetFirstChange? The API allows for notification of changes, but the Notify event has no arguments: presumably you are meant to call GetNextChange and do something or other with the log entry.

Of course developers have shrugged their shoulders and experimented a bit. Some have found Notify failing to fire, particularly with MFC. Others have just been puzzled. I tried it with my C# wrapper and got strange results; I think the only way forward would be to reverse-engineer the log entries to work out what it is they represent.

But what about Microsoft’s developer support? There are managed newsgroups, which are meant to guarantee a response for developers with MSDN subscriptions, as well as other online forums supposedly monitored by Microsoft developers – like Senior Program Manager Dave Massy, who says in his welcome:

Welcome to the MSDN forum for Internet Explorer Addon Development. If you have questions around development of extensions for Internet Explorer then this is the place to ask them.

Perhaps it is; but Massy is strangely silent on the intricacies of IHTMLChangeSink. I have seen this often: easy questions get a ready reponse either from Microsoft or from community members, but the tough ones, where only Microsoft has the answer, are simply ignored; or else there is a request for further information which looks promising at first but leads nowhere. Try Googling on this API; you will find questions but few answers.

My question is this: why bother publishing the API at all if it is so poorly documented and badly supported that nobody can figure out how to use it?

I would guess that this API is or has been used internally, by other Microsoft products that use the IE editor, and that somewhere in the bowels of Redmond there is proper documentation or sample code, perhaps not in sufficiently polished form for general release.

It’s time Microsoft either stopped pretending to offer developer support through these online forums, or put in the effort required to make them work.