Feb 25 2010

Avoid the Undocumented and Unsupported functions

Category: Desktop and Server | MobileJoel Ivory Johnson @ 11:53

Between the MSDN forums and some e-mails that I've received I am seeing a common theme among some of the questions; they deal with undocumented features of Windows phones. My advice when it comes to such features is that it is better to avoid them than to try an figure out how to make something work with an undocumented feature.

One might call me lazy for this, but it is not from laziness that I give this advice. Using undocumented features comes with some risks. One risk is that a program that uses an undocumented feature may have reduced compatibility across devices and firmware versions. My first encounter with this is when I was writing an article on Windows Mobile Power Management. During the time that I was writing it an update was made available for my TyTn II from Windows Mobile 6.0 to 6.1. After the update some of the code examples I had written no longer worked because of changes in the power manager.

If you look through the MSDN documentation on Windows Phones you'll see that it is mixed with the documentation on Windows Embedded CE (which makes since given that that Windows Phone operating systems are derived from Windows Embedded CE. On some of the pages you'll see that a certain feature is supported on Windows Embedded CE but not Supported on Windows Mobile. Sometimes when you will see a feature listed as supported on Windows Embedded CE but not on Windows Phones even though you can find Windows Phones that have the feature implemented. For items like this you'll find that the functionality may be optional (and thus not on all Windows phones) and/or the implementation may have a lot of dependencies on OEM decisions (and may not work the way that you would expect). Another example is customizing a notification icon that shows up in the task bar. Doing this was agains the Made for Windows Mobile guidelines. And if you take a look at Windows Mobile 6.5.3 you'll see that this old technique may not work on newer devices

The ramification of making programs that require functionality that may or may not be present and may or may not behave a certain way when present is that your program could end up with limited compatibility and inconsistent stability across devices.

The same functions are not undocumented and unsupported to every one. OEMs (who are implementing the device, drivers, and portions of the operating system) will have documentation and support for many of the low level functions available in Windows. Manu of these functions aren't mentioned in MSDN documentation. Application developers typically need higher level access to the device and generally less of these functions will be available to them.

I'm not labelling all instances of using undocumented and unsupported features as bad. There are actually quite a few scenarios in which this provides some pretty nice solutions. When applied with discipline everything has its place. So I'm stating this more as a general rule and thing that for the general case these areas of functionality are better left untouched for general development.