Microsoft Research Detours Package, Version 1.5 (Build 46)


DISCLAIMER AND LICENSE:
=======================
The entire Detours package is covered by copyright law.
Copyright 1995-2001, Microsoft Corporation.  Portions of the Detours package
may be covered by patents owned by Microsoft Corporation.  All rights reserved.

Usage of the Detours package is covered under the End User License Agreement in
the file License.doc.  Your usage of Detours implies your acceptance of the End
User License Agreement.  A copy of the license in ASCII can be found in the
file LICENSE.TXT.  A complete list of redistributable files is in REDIST.TXT.


INTRODUCTION:
=============
The file detours.doc contains a paper describing the Detours package.


COMPATIBILITY:
==============
All Detours functions are compatible with all x86 version of Windows NT,
Windows 2000, and Windows XP.  However, under Windows 95, Windows 98, and
Windows ME, the DetourFunction* APIS do not work unless the program is
running under a debugger (the process was created with the DEBUG_PROCESS flag
on the call to the CreateProcess* APIs).  Since most programs are not typically
run under a debugger, the DetourFunction* APIs do not work for most programs
on Win9x platforms.

While Windows NT, Windows 2000 and Windows XP always map DLLs into processes
with copy-on-write mapping (which Detours needs in order to patch the binary
image), Windows 95, Windows 98, and Windows ME only map DLLs with copy-on-write
if the process was started with the DEBUG_PROCESS flag on the call to
CreateProcess.

The DLL injection functions are not compatible with either Windows 95,
Windows 98, or Windows ME as the Win9x platforms do not supports the
CreateRemoteThread API.

The binary rewriting function for adding payloads and modifying import tables
are fully compatible with Windows 95, Windows 98, Windows ME, Windows NT,
Windows 2000, and Windows XP.


BUILD INSTRUCTIONS:
===================
To build the libraries and the sample applications, type "nmake".


VERIFYING THE INSTALL AND BUILD:
================================
After building the libraries and sample applications, you can verify that
the Detours packet works on your Windows OS by running the Test.bat program
in the samples\slept directory.  The output of Test.bat should be similar
to that contained in the file samples\slept\NORMAL.TXT.


MANIFEST:
=========
The Detours package current consists of the Detours library (with or without
source code) and a number of sample programs.  Descriptions of the sample
programs can be found in samples\README.TXT


NOTES:
======
When writing detour functions, it is imperative that the binary-calling
convention of the detour and trampoline functions match exactly the
binary-calling convention of the target function.

In a few cases, when the sizeof() a return value is smaller than sizeof(int),
C or C++ compilers will generate non-compatible binary-calling conventions by
not widening the return value to an int as is customary for small return values.
The result is a syntactically-identical, but not binary-compatible, detour
function.  In most cases, the problem can be fixed be having the detour function
return a value widened to a sizeof(int) type.  Developers are urged to exercise
caution, and should insure that correct code is generated by their C or C++
compiler for detour functions with small return values.

When attaching a DLL to a binary with Detours DLL import APIs, the DLL must
export one procedure with export ordinal 1.  The exported procedure is not
called by the application, but it used as the import target.


BUG REPORTS:
============
Please send detailed bug reports to detours@microsoft.com.  Submitted bug
reports may be used to fix bugs in future versions of the Detours package.
The detours@microsoft.com email address is not a product support alias.
