Microsoft
Detours is a project of Microsoft Research. Detours can be used to
intercept function calls to any DLL in the system and in any process. The technology used by
Detours is patented by Microsoft (see
Patent US20100095281 - Internal Function Debugger). There are both a
Detours Professional and a Detours Express. Detours Professional must be
purchased and is expensive but includes a commercial use license that allows
its use in commercial products. Detours Express is free and has less
features than the proessional edition.
Do you need to intercept native calls to Windows API functions such as
MessageBox and alter what is done by that call? For example, you could
change the text of the message or the MessageBox caption. Or you could
change the name of a file to be opened; not the file itself, but the
filename that is to be opened. Or perhaps you simply need to know what file
that some other software is using. Detours can do that plus much more. If
you have software that draws text graphically and you need to grab that text
programmatically, Detours can do that. Detours is unrelated to hooks such as
what is installed using SetWindowsHookEx.
Detours is very powerful and equally dangerous. It is complex and highly
technical. I don't understand the internals of how it does what it does. To
use Detours, you must have an understanding of how Windows works at the
Windows API level at least. You need to understand how native Windows DLLs
work. If your understanding of what a DLL is is that a DLL is something you
add to a project by creating a refence, then you need to learn more about
DLLs before you can use Detours.
Interception code can be injected into a process during execution using
code that is similar to the Windows API function CreateRemoteThread. The
injected code actually is a DLL and the
DllMain function exeuctes in the
other thread. The DllMain function sets up one or more detours which
intercept calls to specified "target functions". When detoured,
calls (from a "source function") to the target function are
redirected to a "detour function". The address of the detoured
function is saved (in a "trampoline function") so that the detour
function can call the original detoured function before and/or after doing
whatever the detour function needs to do.
Detours is primarily used to intercept calls to native DLLs. The Windows
API is an example of native DLLs; most of the API exists in a few DLLs.
Normally, the source function (in the calling program) calls the target
function in a DLL and the DLL function executes then returns control back to
the calling program. The normal flow without Detours would generally be:
- Source function
- Target function
- Source function
In other words, the DLL function is called. When a function is
intercepted using Detours, the flow would generally be:
- Source function
- Detour function
- [Optional] Trampoline (Target) function
- Detour function
- Source function
As stated above, the call from the Detour function to the Trampoline
(Target) function is optional; the Detour function can entirely replace the
Target function simply by not calling the Trampoline. In that case, the flow
would generally be:
- Source function
- Detour function
- Source function
If the Detour function does not call the Target function then the Detour
can provide totally different behavior without making any changes whatsoever
to the Source function software.
To intercept a call occuring in another process, a Detour function must
exist in a native DLL with unmanaged code. Since injected code must exist in
a native DLL, it is not possible to make a DLL with managed code that is to
to be injected into another process. It is possible however to use Platform
Iinvoke to call the functions that create Detours. Also, Detours can
actually be useful for intercepting calls to a DLL from within the same
process that creates the Detour. This article includes a simple sample use
of Detours from managed code that sets up a managed code function as a
Detour so you can use entirely managed code to experience how awesome
Detours is.
Installing Detours
To use Detours, you must download and install it. You also need to build
it; the source code for Detours is provided but the executable is not
provided. After installing Detours, open the README.TXT file for build
instructions. It says that you need to copy the entire contents of the
detours directory to somewhere else that you have write access. Then you
need to open a command prompt, execute the vcvars32.bat file in the Visual
C++ bin directory to update the path environment variable. Then change the
current directory to the directory that you copied Detours to. Then use the
command "nmake". You should get a large amount of messages sent to the
console window. The build will execute for approximately a couple of
minutes. All of this is relatively crude; it is not the friendliest way to
install software.
Definitions
When I first learned about Detours, the terminology was confusing. I was
not sure what a trampoline is. I hope this article helps make that clear.
- target function
- function to intercept
- detour function
- function that is called instead of the target function
- trampoline function
- the original function that the detour function can (and usually
does) call