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 KNSoft.SlimDetours and the latest Microsoft Detours, include corresponding header (SlimDetours.h or detours.h) and compiled static library to use them.

/* 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", MSBuild sheet in NuGet package cannot determinate automatically the last level directory name ("Release" or "Debug") of library path should be used, add it manually is required, 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:

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/ARM64EC target 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.