Undocumented and Deprecated : APIs you don’t want on your "friends" list


 


There are two kinds of APIs you don’t want to make friends with in this world – undocumented and deprecated.  They are mysterious and seductive.  They allow you to do things we said you couldn’t do.  They continue to work even after we said they wouldn’t (sometimes). 


 


I have to be honest – I’ve used them to.   In my days as a competitive ISV, we did whatever it took to make the application work.  I make no apologies about it.  It’s hard to write bleeding edge software when you are doing it just like everyone else and never pushing the limits.  So be creative – go for it, but understand a couple of things.  You are better off staying away from these guys.  With their friendship, comes great risk and responsibility…


 


Undocumented APIs


Remember all those books that made a “splash” off undocumented APIs for Windows?  It would seem that Microsoft is simply withholding all these great APIs right?  Not really.  When we expose a new feature or API and make it public, it goes through a rigorous process of being approved.  Do developers really need this API?  Is there any other way to do it?  Could this API be used maliciously?  Does it align with our next product/platform releases?  The requirement bar to get something added is extremely high and there are good reasons.


 


As a developer, you know that once you expose a feature (API) – it’s nearly impossible to take it back.   To do so is a very disruptive process and in the case of APIs, breaks code and compatibility to remove them.  If we add too many APIs, then the platforms starts to bloat in size.  People will always use APIs in ways we never intended which is a special risk in itself.  Testing cycles become more complex, etc.


 


APIs are the foundation of any development work and you need a solid foundation – so we plan carefully. 


 


When we publish an API publicly, it’s like a contract between Microsoft and developers that says “we expect you to use this”.  It went through all the quality bars, security reviews, etc.  It’s also a way to ensure compatibility moving forward.  When we change the internals of our code, we try to avoid changing public APIs used to build your application.  You are abstracted from the platform details and so Windows applications continues to work.  We expect you to be using these APIs and therefore, we’re very careful about what we change.


 


What happens when you use an undocumented API?  Let me be blunt — we have no idea you are doing it and you are on your own.  There is no contract.  You are calling into code that was not tested for public consumption.  There are no guarantees of what the side effects could be or what other dependencies may exist.  When we start changing code for version.next, we may unintentionally change the API out from under you.  After all, nobody is expected to be using it because we never published it in the SDK.  When you call Microsoft Support they will not be able to help you if it’s outside their support boundaries.  Again – if we don’t know you are using it, then it’s subject to change without notice.  If your application is dependent on an undocumented API for any piece of functionality, it is very likely to break at some point and put us both in a bad place.  Neither of us want to be there – so don’t use undocumented APIs.  =)


 


Deprecated APIs


These little guys can sneak up on you.  When we determine that an old API is obsolete, we flag it as deprecated in the SDK.  This means it’s going away and will stop working at some point but we typically make every effort to support it for another 1-2 revisions of the platform.  The idea is to give developers time to prepare their apps.  The problem is that many developers never review SDK updates for obsolete APIs and find out the hard way (when things stop working).  Granted … it takes discipline to do this and it’s not always easy to find a quick list.  Jim Wilson just published a new whitepaper on MSDN that covers the current list of APIs being deprecated on Windows Mobile 5.0 and 6  .  I recommend you check it out.


 


Backwards Compatibility


If you stay away from undocumented and deprecated APIs, your backward compatibility story will be much better.  One of the larger desktop apps I built back in the day was on top of Windows 3.0 APIs (even before Windows for Workgroups).  It was in the neighborhood of a million lines of C++ code.  We didn’t have a lot of dependencies on 3rd party components that could break so the vast majority of the app was just Windows API and the C++ runtime.  We didn’t assume (hard code) anything about the network, screen size, etc.  It was a monster of an app by many standards today.  Amazingly, it still runs today on Vista and aside from the Common Color dialog, works just fine.  I’m telling you this to support a point…  if you stick to standard, supported APIs you can avoid a lot of the common problems that break apps between platform releases. 


 


I think our Windows Mobile teams do an amazing job overall at compatibility.  Not only do they have to accept the monumental challenges of maintaining backward compatibility – they have to do it under a stringent memory requirement.   By and large many old PPC apps built on core APIs and using supported libraries will run on WM6 today (they may not look beautiful on that amazing new screen but they run). 


 


All that said…sometimes there are hard decisions to be made that are going to break some apps.  We did with areas in Windows Mobile 2003SE and WM5.  Opening the doors for better displays in 2003SE meant old application may would need some re-work with their UI.  Moving to persistent storage in WM5 meant losing some I/O performance, upgrading all our database code, and making some major memory changes between program/storage that some apps depended on.  But look at the benefits now.  We have amazing displays and you aren’t losing data because your battery runs out.  Tough decisions?  Yes… but sometimes you have to move forward to get better.


 


-Reed


 


 


 


 


 


 


 


 


Comments (4)

  1. akac says:

    Hm. A few comments:

    1) If you don’t want us to use an API, don’t use it yourself *in an app*. For example, if the Pocket PC Contacts app uses an API, then it should be available to all. Or Pocket Word. An *application* that Microsoft writes should only use APIs that third party devs use. Otherwise we have no choice but to find that API out. And I do mean no choice because a choice between doing something and not doing something means I’m going to go write apps for BlackBerry or Symbian instead. An example. POOM. In Wm2000-2003 POOM was far too slow to be used. We were forced, if we wanted to write apps for WM, to go directly to the database. Even in Wm5/6 we still are because POOM is still too slow and customers will simply not use/buy our software. We tried it.

    2) If you’re going to provide APIs – makes sure they work. POOM was notorious for bugs that just shouldn’t have been there. Notes not copying when you do a ::Copy() on a task or appt? Too bad. How about categories being lost in WM2003 on many POOM edits. Data loss here!

    3) So so far I’ve talked about undocumented data structures, not APIs. A database is a database 🙂 But now lets talk about undocumented APIs. Want to get a list of timezones on the device? Good luck. Undocumented APIs are the only way to do it. Thankfully for us, its not a huge deal if you break it…its a small part of the app and we write it so that if it doesn’t exist, we don’t provide that feature. I *hate* using undocumented APIs. But again, what do we do? In the case of timezones we could have our own but if it doesn’t match with the system’s the feature is broken. So in the spec it doesn’t make sense to even have the feature unless its using the system’s time zone list.

    4) On Windows Mobile, unlike Windows Desktop, it makes little sense to write an app that will work 100% from PPC 2000-WM6 because of design. The UI design and underlying assumptions change from OS to OS. An app that was built for PPC 2000 is hardly usable on Wm6. It’ll work, but nobody would buy it.

    Instead its better to design the app to be well factored so any OS specific pieces can be broken into different areas so you can optimize for each flavor properly. In this case, using undocumented/deprecated APIs isn’t that big of a deal because you can put those in the support for older OS’s but not newer.

    Also with the length in time for WM OS’s, I find its better to use whatever makes our apps work the best for that OS. When the next OS comes out we’ll continue to change our software to support it best too. This allows us to also redesign any UI elements that need it to support the new OS.

    My only beef with this whole process is things that are lost in the process. WM2000-Wm6 have the RichInk API for PPC. SP doesn’t. What’s sad about this is that this means no RTF viewing on screen and worse, no conversion between RTF and plain text unless we want to build our own RTF. Its a loss. And for little good reason since MS has a lot of great RTF display/conversion code it could port in as a great supported API if the old code sucked.

  2. Reed Robison says:

    I’m glad you raised those points.

    POOM is a perfect example for this discussion.  You are right – it’s functional but not the most efficient way to do things and many ISVs went straight to the database to get around it.  We told people not to do it because direct DB access was not supported , but I have to agree – there was no other way to get the performance you needed for some 3rd party PIM applications, so some ISVs did it anyway.  Because the structures we’re never publically exposed, we changed them and those changes broke code for any applications that used unsupported, direct database access.  This is the “risk” I’m talking about with unsupported and deprecated APIs.  Sometimes there are good reasons to go this route, but you assume the risks.  

    Why not just support direct database access or expose all APIs?

    As good as it sounds to say something like “don’t use any APIs you don’t expose to ISVs”, that’s a whole lot easier said than done.  Would you let anyone call into your code anywhere they wanted to?  Are all your APIs customer ready?  Do they have any dependencies to system states or other private structures that may have not been properly initialized?  Could they be used maliciously?  Could you guarantee that your app would work if someone was randomly altering the database underneath it?  There is simply no way expose EVERYTHING and ensure any level of platform stability or security.  APIs are an abstraction layer in every sense.

    Even though the PIM database structures under POOM were subject to “change without notice”, we told developers this was coming for a year+ before WM5 shipped.  We talked about it in webcasts, MEDC, MSDN papers, blogs, etc.  We did our level best to let developers know even though it was unsupported so they would have time to prepare.  We don’t want you in this position.

    Some of the TIMEZONE information is published publically, but if there is anything you guys *really* need that we don’t publish—LET US KNOW.  Come to MEDC and provide feedback.  If you can’t attend, then be vocal on the community forums.  Ask for things in the MSDN and Windows Mobile blogs.  I’ll be happy to file the feature request.  I can’t promise it will make it in the product right away, but I promise to get your “ask” in there.  Like any software release, features and APIs are prioritized and added based on demand.  If enough people demand a feature – it will happen.

    http://support.microsoft.com/kb/923953

    I pretty much agree with you on #4.  My point was that by sticking to standard APIs things are more likely to work between releases and that puts you in control over your update and release cycle.  That way, you can release an update when it makes business sense for you and not in “reactive” mode when a customer calls to report the app broke on a new device they just bought.  

    Thanks for your feedback – good points!

  3. Lors de vos développements Windows Mobile, vous avez peut-être utilisé ou cherché à utiliser des API

  4.   July is a special time around Microsoft.  It’s the start of a new fiscal year…