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的支持
  • 更小的二进制体积

• 新功能

  • [草稿] 支持延迟挂钩（目标DLL加载时自动挂钩） 🔗 技术Wiki：实现延迟挂钩
  • [草稿] COM Hook

  以及此处的待办列表。

用法

提要

KNSoft.SlimDetours包体同时含有SlimDetours与原版Microsoft Detours。

对于KNSoft.SlimDetours包含SlimDetours.h头文件，或者对于原版Microsoft Detours包含detours.h头文件，然后链接编译出的库KNSoft.SlimDetours.lib。

NuGet包KNSoft.SlimDetours是开箱即用的，只要安装到项目，编译好的库就会自动加入链接。

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

如果你项目的配置名称既不是“Release”也不是“Debug”，NuGet包中的MSBuild表单无法自动链接编译好的库，需要手动链接，例如：

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

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

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

延迟挂钩

“延迟挂钩”将在目标DLL加载时自动挂钩，在NT6+上支持。

比如，调用SlimDetoursDelayAttach来在a.dll加载时自动挂勾a.dll!FuncXxx：

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

演示：DelayHook.c

兼容性

项目构建：主要考虑对最新MSVC生成工具和SDK的支持。本项目代码能向下兼容MSVC生成工具与GCC，但具体还要看其依赖的NDK，参考SlimDetours.NDK.inl。支持随ReactOS一同构建。

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

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

Caution

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

协议

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

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

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