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

 

KNSoft.SlimDetours

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

Compared to the original Detours, the advantages are:

• Improved
  • Automatically update threads when set hooks 🔗 TechWiki: Update Threads Automatically When Applying Inline Hooks
  • 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 is out-of-the-box, contains both of SlimDetours and the original Microsoft Detours, install to project and the compiled library will be linked automatically.

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

#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();

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. The minimum target platform is NT6 by default, specifying the _WIN32_WINNT macro in compiling-time to build binaries that target to lower NT versions.

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. Some APIs may be altered frequently, please keep an eye out for the release notes.

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.