The purpose of this post is nothing more than just entertainment. So if you don't want to waste time, then don't read it.
With this post I am also starting a new series. Quite often during reverse engineering I encounter some strange functions and variable names, as well as weird implementation, or documentation so silly that you can't stop wondering - "what was that for?"
Most times I just chuckle alone, or share it with my friend, and in most cases it goes nowhere. With this series I'm planning to share it with you, so that just maybe it will lighten up your programming day as well.
So let's begin.
Microsoft use RPC extensively in their APIs. Quite often they relay execution from their DLL to a system service using RPC. Some of the APIs that are used for this technique are documented, but most are not.
What is the state of documentation for the NdrClientCall3 function (or NdrClientCall4 in that matter) is something that I will leave up to you.
As of the writing of this blog post it looked like this:
This function is used to initiate an RPC request from a client process to a server. And even though one can deduce the meaning of some of its parameters, the question that still remains in my mind - "What was the point of documenting it, if the documentation doesn't say anything relevant about that API?"
Wouldn't it be easier to let the intern, who drew a short straw to type these, to go home instead of having them produce documentation like that?
This is another example of a function that was a Friday-night last hoorah of an unfortunate intern who was tasked to type these up. At times I seriously question whether or not the person who was punished to type this documentation had any idea what all these weird words mean.
The ApiSetQueryApiSetPresence function deals with a poorly documented concept of API-sets, or umbrella libraries. These could be viewed as virtual DLLs that don't really exist as physical files on disk under that specific name, and are redirected to other "real DLLs". My guess is that Microsoft introduced these API-sets in hope of resolving the DLL mess that has been created by their developers over the years.
The question still remains - "What was the point to create a documentation for this API if it doesn't really serve any purpose, other than saying that it's an internal function?"
Sure, we know that it's an internal function. Among many others that one can find by searching System32 folder. But for some reason Microsoft don't waste time of interns to issue similarly useless documentation for those functions, do they?
Honorable Mention - BindIoCompletionCallback Function
This one comes from Rbmm. The
BindIoCompletionCallback function has a very weird description of its return value:
The person typing it up evidently copy-and-pasted it from somewhere else, possibly from the description of the FileIOCompletionRoutine routine, because there's really no "return value" which is NTSTATUS. The function returns BOOL.
So to be correct, the documentation should have just stated this:
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call the GetLastError function.
Alternatively, if you interpret it the other way, the GetLastError function returns just a plain old OS error code, and not the NTSTATUS, like that MSDN page claims.
And speaking of the
FileIOCompletionRoutine callback (this one also comes from Rbmm) the documentation for its
dwErrorCode parameter is wrong. It claims that:
The I/O completion status. This parameter can be one of the system error codes.
Strictly speaking, the nature of the
dwErrorCode parameter depends on where that callback was invoked from.
For instance, it may have been specified in the
WriteFileEx functions, in which case
dwErrorCode will be indeed one of the system error codes, like documentation claims.
But, if it was specified in the
BindIoCompletionCallback function, the
dwErrorCode parameter will be filled directly from the Kernel and will contain one of the Kernel-like NTSTATUS return values, and the documentation will be wrong. In that case to convert it to the system error code, one needs to call RtlNtStatusToDosError on it.
In all honesty though, Microsoft should have used a different declaration for the callback for
BindIoCompletionCallback and not reused the existing one.
Logical Bug in the DnsQueryEx Function
So stepping away from the silly documentation, Rbmm shared a more serious issue - a logical bug in the
More precisely, it's a bug in the implementation of that API. It manifests itself when the
DnsQueryEx is called in an asynchronous mode, or when
DNS_QUERY_REQUEST struct is not NULL, and if the IP address supplied for that function can be resolved synchronously (say, in case of a
localhost or a loopback.)
In that case the
DnsQueryEx returns ERROR_SUCCESS, but the
pQueryRecords member of the
DNS_QUERY_RESULT struct will be NULL, and the resulting DNS query will be lost.
A workaround in this case will be to call
DnsQueryEx synchronously, but that defeats the purpose of calling it asynchronously in the first place.
Lastly, I want to showcase a few silly function names that I came across while reverse engineering Windows components.
One is the function named
EagerlyInitializeProcessChannel, that is present in the Microsoft public symbols for the
combase.dll module. It is called from another internal function
combase!ProcessInitialize, in response from a documented
It has the following signature:
void EagerlyInitializeProcessChannel(_TP_CALLBACK_INSTANCE *,void *,_TP_WORK *)
I really don't know why it is so "eager" to initialize, and what it is initializing? Nor that I was willing to spend any more time to reverse-engineer it to know the answer. For me, it was just an example of a goofy name of an internal function that no-one (except maybe for its original author) was probably aware of ... until today.
"Quirks" In The Machine
Another funny name, or more precisely, the whole API-set that Microsoft is using, is a class of "Quirky" APIs.
I'm not kidding. If you search the System32 directory for any function names containing a combination of the word "quirk", you'll see a lot of imported API names with that combination:
It's hard to say what is so quirky about it, but Microsoft has the whole two API-sets with that name:
api-ms-win-core-quirks-l1-1-1.dll. And if you dig into the internals of the
CoInitializeEx function, using Microsoft public symbols, and place a breakpoint in the
combase.dll module on:
bool __fastcall IsThresholdAppLaunchPerfFeatureEnabled();
You will notice that one of the branches inside that function invokes the following internal call to:
bool Quirks::IsQuirkEnabled(Quirks::QuirkStatus *,ulong);
Also, as I noted above,
QuirkIsEnabled is an exported function from the Microsoft's virtual libraries, or API-sets, as well as from
KERNELBASE.dll. Additionally, if we dig deeper, that function invokes
KERNELBASE.dll!IsQuirkIsEnabledForPackageWorkerPresent, that in turn invokes our previous friend
ApiSetQueryApiSetPresence with the name-set
As with a previous example though, it is hard to tell for sure what kinds of quirks this class of functions addresses without dedicating too much time to reverse engineering it. Or, maybe someone can ask Raymond Chen about it?
This was just a small sample of weird and quirky stuff that I came across while developing for or reverse engineering Microsoft Windows. I am sure there will be many more parts to this series. So stay tuned ...