Crossing the Undocumented Line
As a consultant who has more than once taken on projects Microsoft has said are impossible, many people assume I often use undocumented calls in Windows in my work. In fact, I try to avoid them if at all possible, and am extremely careful in crossing the undocumented line.
A developer should ask a set of questions when considering using an undocumented technique; these are:
There are calls that have been in the Microsoft DDK include files for years, but are not documented. For example, a number of the ZwXXX calls have options that are not described in the documentation, but are in the includes with all the needed data structures.
- Is it really needed? Before anything else, ask yourself if there is any other way to do this. Be sure to not constrain your design when you ask this question. For instance, requiring something be done in the kernel may force an undocumented technique where building a helper application could allow a documented approach.
- How undocumented is it? There is a lot of variation here; there are plenty of undocumented calls that are never mentioned by Microsoft. These I consider pretty undocumented even if there are examples on the web.
Another variant of undocumented is the call that is documented in later OS’s but works for your driver in previous versions. In the early days of the DDK, there were calls in the samples that were not documented. These calls are not completely safe, but they are better than the totally undocumented calls.
- Which OS’s require the undocumented stuff? If you are looking at an undocumented call for an older OS, the function you need in later OS’s is not present, so you are probably safer than expecting a call to be there in the future.
- What is the scope of the input and usage of the undocumented stuff? If you are using the undocumented calls in a constrained environment you are in a safer position than a having a widespread and flexible use. It is hard to test any piece of code, but if the inputs or patterns of use vary, the testing of this area just got harder.
- What is the fallback plan? If you do go ahead and do this, what will you do if it breaks tomorrow? Has your design kept the undocumented stuff limited so it can be replaced in the code? Is there likely to be an alternative for the replacement? What is the plan if there is no replacement?
If you decide you have to cross the line and use an undocumented call, there are some things you should be doing:
· Let the customer know – Document the call and the answers to the above questions to the customer or your management. Crossing the line should be a decision made by more than just the developer.
· Plan for a long testing cycle – You have chosen to use something you cannot rely on, so your testing pain just went up. You really need to test all the likely OS configurations the end user could have. This means not just testing on the current version of a Windows OS, but instead the base, all service packs, and the current version , i.e., all the latest hotfixes and downloads. For 32-bit Windows, that is sixteen full tests if you want to support Windows 2000 up to Vista!
There are times to cross the line, but be sure you have a plan and a strong justification before you enter the undocumented territory.