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

 

KNSoft.SlimDetours

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

Compared with the original Detours, it has the following advantages:

• Improved
  • Automatically updates threads when applying hooks 🔗 TechWiki: Update Threads Automatically When Applying Inline Hooks
  • Avoid heap deadlocks when updating threads 🔗 TechWiki: Avoid Heap Deadlocks When Updating Threads
  • Avoid occupying system-reserved memory regions 🔗 TechWiki: Avoid Occupying System Reserved Region When Allocating Trampoline
  • Other bug fixes and code improvements
• Lite
  • Depends on Ntdll.dll only
  • Retains only API hooking functions
  • Removes support for ARM (ARM32) and IA64
  • Smaller binary size

See also the Todo List.

Usage

TL;DR

The KNSoft.SlimDetours package is ready to use out of the box. It contains both KNSoft.SlimDetours and the latest Microsoft Detours, and includes the corresponding headers (SlimDetours.h or detours.h) and compiled static libraries.

/* KNSoft.SlimDetours */
#include <KNSoft/SlimDetours/SlimDetours.h>
#pragma comment(lib, "KNSoft.SlimDetours.lib")

/* Microsoft Detours */
#include <KNSoft/SlimDetours/detours.h>
#pragma comment(lib, "Microsoft.Detours.lib")

If your project configuration name contains neither "Release" nor "Debug", the MSBuild property sheet in the NuGet package cannot automatically determine which final library-path directory ("Release" or "Debug") should be used, so you need to add it manually. For example:

#if DBG
#pragma comment(lib, "Debug/KNSoft.SlimDetours.lib")
#else
#pragma comment(lib, "Release/KNSoft.SlimDetours.lib")
#endif

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

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

For a more simplified API, see InlineHook.c.

Details

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

• Function names begin with "SlimDetours"
• Most return values are HRESULT values that wrap NTSTATUS through the HRESULT_FROM_NT macro; use macros such as 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 build tools and SDKs is the main focus. The code in this project remains backward-compatible with MSVC build tools and GCC, but actual compatibility also depends on the NDK it uses; see SlimDetours.NDK.inl. It can also be built together with ReactOS. The default minimum target platform is NT6; specify the _WIN32_WINNT macro at compile time to build binaries that target lower NT versions.

Artifact integration: broadly compatible with MSVC build tools (VS2015 is known to be supported) and different compilation configurations (e.g., /MD, /MT).

Runtime environment: NT5 or later, x86/x64/ARM64/ARM64EC target platforms.

License

KNSoft.SlimDetours is licensed under the MIT license.

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

It also uses KNSoft.NDK to access low-level Windows NT APIs and its unit test framework.