Those MS API disclosures – errors, incomplete, useless?

Earlier this week Microsoft posted details of a large number of APIs (272, we are told - we have not counted) in the MSDN library. This publication is intended to to comply with the terms of the MS-DoJ proposed settlement to the antitrust suit, and is part of a process whereby Microsoft 'levels the playing filed' for rival software publishers and developers by disclosing APIs and protocols, and offering them for license.

But the API disclosure seems at best utterly irrelevant, and at worst counter-productive, because it is not complete, and some of the information is misleading or wrong. Henk Devos, author of Registry Explorer (an alternative to regedit), has reviewed the documentation since it went up on Monday US time, and says it contains errors, and there are still some things that have been left out. He gives the examples of IBrowserFrameOptions and IDelegateFolder as missing (he says he's figured out the second anyway, but not the first), and that "now that SHCreateShellFolderViewEx has finally been documented after 7 years, the docs are wrong. The structure that they describe for the parameter is wrong."

"This is not intentional, it's just a mistake," he adds. This sort of stuff however does tend to confirm The appropropriately-named Register's long-term belief that what Microsoft has got in there is a grotesque, badly-documented pile of poo it doesn't fully understand itself.

It also seems to be the case that there are substantial numbers that have deliberately not been documented in this exercise, on the basis that these may change or disappear in the near future, and should therefore in Microsoft's view be avoided. This is, friends, plus ca change. As a developer you get some information about Microsoft APIs, but there are ones you don't know about, undocumented ones you use but maybe shouldn't, ones you don't know about that maybe Microsoft developers use (but maybe shouldn't)... So why is this any different from what it was before?

Devos' verdict is that: "All I can say is that this documentation is worthless. There is nothing in it that was not available publicly on the internet by now, except maybe for the Shell_MergeMenus which has some flags that I didn't know what they were. I did not look at all the functions, there might be a few other that were unknown so far. But these certainly won't help me. Another clear mistake, that cannot be completely unintentional, is the information about which Windows versions the interfaces are available on.

"Some functions that have been documented on the internet as long as 7 years ago are now supposedly available only from Windows 2000 on. They now claim that 'All have been documented to the same level of detail Microsoft uses for standard Windows APIs'. This is a real joke. All they did was list the signatures of the functions, and in some cases flags. You will never find any information on what it does, how to use it, where it is used... This was already the case for interfaces that were new for Windows XP and that have been documented. And there is still no information at all about how to achieve certain tasks."

By coincidence, The Register discussed Microsoft's disclosures with Opera Software CEO Jon von Tetzchner earlier this week. Opera is one of the companies that could be though to benefit from some aspects of the settlement. Von Tetchner, however, is unenthusiastic, describing the modded add-remove routine that's supposed to allow you to substitute middleware as "more work [for Microsoft's rivals] and definitely not positive. He also notes that as Microsoft's software is still there, but hidden, there's no chance of OEMs getting a lower price, and therefore being receptive to the idea of shipping substitutes instead.

And the APIs? He says he hasn't looked for them (just as well, Jon - Henk tells us you pretty well need to know what it is first in order to find it), as he's got better things to do, but he fears that making them more widely available is good for Microsoft, rather than its rivals. Adequate documentation would certainly make it easier for developers to work with Microsoft software, and as the software is still on the system, the APIs are still exposed (which is why Microsoft argued that the software would have to stay on the system). "The whole thing's a publicity stunt," von Tetchner told us. ®