README.md

English (en-US)	简体中文 (zh-CN)

KNSoft.SlimDetours

SlimDetours is an improved Windows API hooking library base on Microsoft Detours.

Feature

Compared to the original Detours, the advantages are:

• New feature
  • Support delay hook (set hooks automatically when target DLL loaded) 🔗 TechWiki: Implement Delay Hook
  • Automatically update threads when set hooks 🔗 TechWiki: Update Threads Automatically When Applying Inline Hooks
• Improved
  • Avoid deadlocks when updating threads 🔗 TechWiki: Avoid Deadlocking on The Heap When Updating Threads
  • Avoid occupying system reserved memory region 🔗 TechWiki: Avoid Occupying System Reserved Region When Allocating Trampoline
  • Other bug fixes and code improvements
• Lite
  • Depends on Ntdll.dll only
  • Retain API hooking functions only
  • Remove support for ARM (ARM32), IA64
  • Smaller binary size

And here is a Todo List.

Usage

TL;DR

KNSoft.SlimDetours package contains both of SlimDetours and the original Microsoft Detours.

Include header SlimDetours.h for KNSoft.SlimDetours, or header detours.h for the original Microsoft Detours, then link compiled library KNSoft.SlimDetours.lib.

NuGet package KNSoft.SlimDetours is out-of-the-box, install to project and the compiled library will be linked automatically.

#include <KNSoft/SlimDetours/SlimDetours.h> // KNSoft.SlimDetours
#include <KNSoft/SlimDetours/detours.h>     // Microsoft Detours

If your project configuration name is neither "Release" nor "Debug", MSBuild sheet in NuGet package cannot link compiled library automatically, link manually is required, for example:

#pragma comment(lib, "Debug/KNSoft.SlimDetours.lib")

The usage has been simplified, e.g. the hook only needs one line:

SlimDetoursInlineHook(TRUE, (PVOID*)&g_pfnXxx, Hooked_Xxx);  // Hook
...
SlimDetoursInlineHook(FALSE, (PVOID*)&g_pfnXxx, Hooked_Xxx); // Unhook

For more simplified API see InlineHook.c.

Details

The original Microsoft Detours style functions are also retained, but with a few differences:

• Function name begin with "SlimDetours"
• Most of return values are HRESULT that wraps NTSTATUS by HRESULT_FROM_NT macro, use macros like SUCCEEDED to check them.
• Threads are updated automatically, DetourUpdateThread has been omitted.

hr = SlimDetoursTransactionBegin();
if (FAILED(hr))
{
    return hr;
}
hr = SlimDetoursAttach((PVOID*)&g_pfnXxx, Hooked_Xxx);
if (FAILED(hr))
{
    SlimDetoursTransactionAbort();
    return hr;
}
return SlimDetoursTransactionCommit();

Delay Hook

"Delay Hook" will set hooks automatically when target DLL loaded, supported on NT6+.

For example, call SlimDetoursDelayAttach to hook a.dll!FuncXxx automatically when a.dll loaded:

SlimDetoursDelayAttach((PVOID*)&g_pfnFuncXxx,
                       Hooked_FuncXxx,
                       L"a.dll",
                       L"FuncXxx",
                       NULL,
                       NULL);

Demo: DelayHook.c

Compatibility

Project building: support for the latest MSVC generation tools and SDKs is mainly considered. The code in this project is backwards compatible with the MSVC generation tool and GCC, but it depends on the NDK it depends on, see also SlimDetours.NDK.inl. Can be built with ReactOS.

Artifact integration: widely compatible with MSVC generation tools (support for VS2015 is known), and different compilation configurations (e.g., /MD, /MT).

Runtime environment: NT5 or above OS, x86/x64/ARM64 platforms.

Caution

In beta stage, should be used with caution.

License

KNSoft.SlimDetours is licensed under the MIT license.

Source is based on Microsoft Detours which is licensed under the MIT license.

Also uses KNSoft.NDK to access low-level Windows NT APIs and its Unit Test Framework.