# Detours-Express-2.1
Microsoft Research Detours Package, Express Version 2.1 Build_216. This is a precompiled version using VS2015.
DISCLAIMER AND LICENSE:
=======================
The entire Detours package is covered by copyright law.
Copyright (c) Microsoft Corporation. All rights reserved.
Portions may be covered by patents owned by Microsoft Corporation.
Usage of the Detours package is covered under the End User License Agreement.
Your usage of Detours implies your acceptance of the End User License Agreement.
If you distribute programs which use Detours, you must also distribute a
copy of DETOURED.DLL, which is required for your program to execute.
DETOURED.DLL is built when you build the libraries.
A complete list of redistributable files is in REDIST.TXT.
1. INTRODUCTION:
================
This document describes the installation and usage of this version of the
Detours package. In particular, it provides an updated API table.
Complete documentation for the Detours package, including a detailed API
reference can be found in the Detours.chm file.
2. BUILD INSTRUCTIONS:
======================
To build the libraries and the sample applications, type "nmake".
3. 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 type "nmake test" in the
samples\slept directory. The output of "namke test" should be similar
to that contained in the file samples\slept\NORMAL.TXT.
4. CHANGES IN VERSION 2.1:
==========================
The following major changes were made in Detours 2.1 from Detours 2.0:
* Addition of support for 64-bit code on Itanium 2 processors, using the
IA64 instruction set.
* Correction to disassembly table for X86 for indirection instructions
with either 8-bit or 32-bit constant operands.
The following major changes were made in Detours 2.0 from Detours 1.5:
* Complete API documentation.
* Support for 64-bit code on X64 processors.
* Addition of a transactional model for attaching and detaching detours.
* Addition of code for updating peer threads when adjusting detours.
* Replaced trampoline pointers with target pointers in the API to simplify usage.
* Support for detection of detoured processes.
* Significant compatibility fixes in the DetourCreateProcessWithDll API.
* Removed the DetourContinueProcessWithDll API.
* Added DetourCopyPayloadToProcess API to copy payloads to target processes.
4.1. COMPLETE API DOCUMENTATION:
================================
Detours 2.1 includes extensive online documentation in the Detours.chm file.
The documentation includes a technical overview of the Detours package, an
extensive API reference, descriptions of all of the Detours samples with
cross-links to the relevant APIs, and a list of Frequently Asked Questions
(FAQ) and answers.
4.2. 64-BIT SUPPORT:
====================
Detours 2.1 adds support 64-bit execution on X64 and IA64 processors.
Detours understands the new 64-bit instructions of the X64 and IA64 and can
detour 64-bit code when used in a 64-bit process. However, Detours does not
support cross-compatibility between 32-bit and 64-bit code. For example,
32-bit detours can be applied only to 32-bit code, and 64-bit detours can be
applied only to 64-bit code.
4.3. TRANSACTIONAL MODEL AND THREAD UPDATE:
===========================================
Typically, a developer uses the Detours package to detour a family of
functions. Race conditions can be introduced into the detour code as the
target functions are detoured one by one. Also, the developer typically
wants a error model in which all target functions are detours entirely or
none of the target functions are detoured if a particular function can't
be detoured. In previous version of Detours, programmers either ignored
these race and error conditions, or attempted to avoid them by carefully
timing the insertion and deletion of detours.
To simplify the development model, Detours 2.1 use a transactional model for
attaching and detaching detours. Your code should call DetourTransactionBegin
to begin a transaction, issue a group of DetourAttach or DetourDetach calls to
affect the desired target functions, call DetourUpdateThread to mark threads
which may be effected by the updates, and then call DetourTransactionCommit to
complete the operation.
When DetourTranactionCommit is called, Detours suspends all effected
threads (except the calling thread), insert or removes the detours as
specified, updates the program counter for any threads that were running
inside the effected functions, then resumes the effected threads. If an
error occurs during the transaction, or if DetourTransactioAbort is
called, Detours safely aborts all of the operations within the transaction.
From the perspective of all threads marks for update, the entire
transaction is atomic, either all threads and functions are modified,
or none or modified.
4.4. REPLACED TRAMPOLINE POINTERS WITH TARGET POINTERS IN THE API:
====================================================================
A trampoline is a small block of code modified by Detours to contain the
instructions of the target function moved to insert the detour and a jump
to the remainder of the target function. In previous versions of Detours,
trampolines where managed by the developer. Detours made this as easy
as possibly by providing C macros to statically create new trampolines,
but developer code was prone to undetected mismatches in function
signatures between target functions, detour functions and trampolines. In
addition, the developers were forced to use different APIs for statically
and dynamically available functions. With Detours 2.1, the allocation,
construction, and management of trampolines is controlled completely by
Detours.
Instead of directly using trampolines, developers should now use target
pointers to refer to target functions. Initially, the target pointer
should point to the target function. When a detour is attached to the
target function, Detours will allocate a trampoline function, and update
the target pointer to point to the trampoline. When the detour is
detached from the target function, Detours will restore the target pointer
to the target function and release the trampoline. Thanks to common C/C++
syntax, target pointers can be used exactly like functions.
The most important benefit of using target pointers, instead of trampolines
directly, is that C and C++ compiler check the check the equality of calling
conventions on function pointer assignment. As a result, any discrepancy
between the calling conventions of a target function and a detour function
will be detected at compile time, rather than appear at runtime as mysterous
bugs caused by stack misalignment.
Another benefit of using target pointers is the reduction in the Detours APIs
as the same APIs cab be used regardless of whether the address of a target
function is available at link time or must be derived dynamically.
4.5. SUPPORT FOR DETECTION OF DETOURED PROCESSES:
=================================================
Detours loads the detoured.dll shared library stub into any process which has
been modified by the insertion of a detour. This allows the Microsoft Customer
Support Services (CSS) and the Microsoft Online Crash Analysis (OCA) teams to
quickly and accurately determine that the behavior of a process has been
altered by a detour. CSS does not provide customer assistance on detoured
products.
4.6. SIGNIFICANT COMPATIBILITY FIXES IN THE DETOURCREATEPROCESSWITHDLL API:
===========================================================================
The DetourCreateProcessWithDll API has been completely rewritten. The
previous version of the API used a code injection mechanism to create a
call to LoadLibrary in the target process. The code injection mechanism
could fail silently without any diagnostic information and was suscept
