Intro

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.

NdrClientCall3 Function

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:

MSDN documentation for the NdrClientCall3 function.

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?

ApiSetQueryApiSetPresence Function

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.

MSDN documentation for the ApiSetQueryApiSetPresence function.

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:

MSDN documentation for the BindIoCompletionCallback function's 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:

Return value

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.

FileIOCompletionRoutine Callback

And speaking of the FileIOCompletionRoutine callback (this one also comes from Rbmm) the documentation for its dwErrorCode parameter is wrong. It claims that:

[in] dwErrorCode

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 ReadFileEx or 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 DnsQueryEx function.

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 pQueryCompletionCallback in 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.

"Eager Initialization"

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 CoInitializeEx.

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:

WinAPI Search tool when used to search System32 folder for API names containing the word "quirk".

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-0.dll and 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 "BD".

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?

Conclusion

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 ...