README.zh-CN.md

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

 

KNSoft.SlimDetours

SlimDetours是一个基于Microsoft Detours改进而来的Windows API挂钩库。

相比于原版Detours，有以下优势：

• 经改进

  • 挂钩时自动更新线程 🔗 技术Wiki：应用内联钩子时自动更新线程
  • 更新线程时避免堆死锁 🔗 技术Wiki：更新线程时避免堆死锁
  • 避免占用系统保留的内存区域 🔗 技术Wiki：分配Trampoline时避免占用系统保留区域
  • 其它Bug修复与代码改进

• 轻量

  • 仅依赖Ntdll.dll
  • 仅保留API挂钩函数
  • 移除对ARM (ARM32)、IA64的支持
  • 更小的二进制体积

  以及此处的待办列表。

用法

提要

KNSoft.SlimDetours NuGet包是开箱即用的，同时含有SlimDetours与最新的Microsoft Detours，包含对应的头文件（SlimDetours.h or detours.h）和编译出的静态库以使用它们。

/* 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")

如果你项目的配置名称既不包含“Release”也不包含“Debug”，NuGet包中的MSBuild表单无法自动确定库路径的最后一层目录名（"Release"或"Debug"），需要手动加上它，例如：

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

用法已进行了简化，例如挂钩仅需一行：

SlimDetoursInlineHook(TRUE, (PVOID*)&g_pfnXxx, Hooked_Xxx);  // 挂钩
...
SlimDetoursInlineHook(FALSE, (PVOID*)&g_pfnXxx, Hooked_Xxx); // 脱钩

更多简化的API参考InlineHook.c。

详细说明

原版Microsoft Detours风格的函数也有保留，但有少许不同：

• 函数名以"SlimDetours"开头
• 大多数返回值是用HRESULT_FROM_NT宏包装NTSTATUS而来的HRESULT，使用类似SUCCEEDED 的宏检查它们。
• 线程会被自动更新，DetourUpdateThread已被省去。

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

兼容性

项目构建：主要考虑对最新MSVC生成工具和SDK的支持。本项目代码能向下兼容MSVC生成工具与GCC，但具体还要看其依赖的NDK，参考SlimDetours.NDK.inl。支持随ReactOS一同构建。SlimDetours默认最低目标平台为NT6，编译时指定_WIN32_WINNT宏可以构建支持更低NT版本的二进制。

制品集成：广泛地兼容MSVC生成工具（已知支持VS2015），以及不同编译配置（如/MD、/MT）。

运行环境：NT5及以上操作系统，x86/x64/ARM64/ARM64EC目标平台。

Caution

处于beta阶段，应慎重使用。有些API可能频繁调整，请留意发行说明。

协议

KNSoft.SlimDetours根据MIT协议进行许可。

源码基于Microsoft Detours，其根据MIT协议进行许可。

同时使用了KNSoft.NDK以访问底层Windows NT API及其中的单元测试框架。