From 4a8c5da62c8aef8ce1a103b0168f47ab07a2cc77 Mon Sep 17 00:00:00 2001 From: Ratin Gao Date: Fri, 9 Aug 2024 23:01:37 +0800 Subject: [PATCH] [DOCS] Fix and update documentations --- .../README.md | 4 ++-- README.md | 24 +++++++++++-------- README.zh-CN.md | 22 ++++++++++------- 3 files changed, 29 insertions(+), 21 deletions(-) diff --git a/Docs/TechWiki/Update Threads Automatically When Applying Inline Hooks/README.md b/Docs/TechWiki/Update Threads Automatically When Applying Inline Hooks/README.md index 5179432..09441ef 100644 --- a/Docs/TechWiki/Update Threads Automatically When Applying Inline Hooks/README.md +++ b/Docs/TechWiki/Update Threads Automatically When Applying Inline Hooks/README.md @@ -9,7 +9,7 @@ Inline hook has to modify the instructions at the beginning of the function to implement the jump, in order to cope with the possibility that a thread is running on the instruction to be modified, it's necessary to update the thread in this state to avoid executing an illegal combination of old and new instructions. -## Implementations on other hooking library +## Implementations on other hooking libraries ### Detours @@ -30,7 +30,7 @@ But [Detours](https://github.com/microsoft/Detours) updates threads very precise ### mhook -[mhook](https://github.com/martona/mhook) updates threads automatically when set (or unset) hooks, the caller doesn't need to be concerned about this problem, see [mhook/mhook-lib/mhook.cpp at e58a58ca · martona/mhook](https://github.com/martona/mhook/blob/e58a58ca31dbe14f202b9b26315bff9f7a32598c/mhook-lib/mhook.cpp#L557) for implementation. +[mhook](https://github.com/martona/mhook) updates threads automatically when set (or unset) hooks, see [mhook/mhook-lib/mhook.cpp at e58a58ca · martona/mhook](https://github.com/martona/mhook/blob/e58a58ca31dbe14f202b9b26315bff9f7a32598c/mhook-lib/mhook.cpp#L557) for implementation. But the way it updates threads is a bit hacky compared to the others mentioned above, wait 100ms if the thread is exactly in the area where the instruction is about to be modified, try up to 3 times: ```C diff --git a/README.md b/README.md index eeb4509..91168fc 100644 --- a/README.md +++ b/README.md @@ -23,10 +23,10 @@ Compared to the original [Detours](https://github.com/microsoft/Detours), the ad - Lite - **Depends on `Ntdll.dll` only** - Retain API hooking functions only - - Remove support for ARM (ARM32), IA64, WinXP, GNUC + - Remove support for ARM (ARM32), IA64 - Smaller binary size -- Out-of-the-box - - NuGet package is released + +And here is a [Todo List](https://github.com/KNSoft/KNSoft.SlimDetours/milestones?with_issues=no). ## Usage @@ -50,7 +50,15 @@ If your project configuration name is neither "Release" nor "Debug", [MSBuild sh #pragma comment(lib, "Debug/KNSoft.SlimDetours.lib") ``` -Usage is similiar to the original [Microsoft Detours](https://github.com/microsoft/Detours), but: +The usage has been simplified, e.g. the hook only needs one line: +```C +SlimDetoursSetHook((PVOID*)&g_pfnXxx, Hooked_Xxx); +``` +For more simplified API see [Wrapper.c](https://github.com/KNSoft/KNSoft.SlimDetours/blob/main/Source/SlimDetours/Wrapper.c). + +### Details + +The original [Microsoft Detours](https://github.com/microsoft/Detours) style functions are also retained, but with a few differences: - Function name begin with `"SlimDetours"` - Most of return values are [`HRESULT`](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-erref/0642cb2f-2075-4469-918c-4441e69c548a) that wraps [`NTSTATUS`](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-erref/87fba13e-bf06-450e-83b1-9241dc81e781) by [`HRESULT_FROM_NT`](https://learn.microsoft.com/en-us/windows/win32/api/winerror/nf-winerror-hresult_from_nt) macro, use macros like [`SUCCEEDED`](https://learn.microsoft.com/en-us/windows/win32/api/winerror/nf-winerror-succeeded) to check them. @@ -69,10 +77,6 @@ if (FAILED(hr)) } return SlimDetoursTransactionCommit(); ``` -If you feel the above Detours-style API calls complicated, [SlimDetours](https://github.com/KNSoft/KNSoft.SlimDetours) provides some APIs in [Wrapper.c](https://github.com/KNSoft/KNSoft.SlimDetours/blob/main/Source/SlimDetours/Wrapper.c), which can do the job with just one line, such as: -```C -SlimDetoursSetHook((PVOID*)&g_pfnXxx, Hooked_Xxx); -``` ### Delay Hook @@ -91,11 +95,11 @@ Demo: [DelayHook.c](https://github.com/KNSoft/KNSoft.SlimDetours/blob/main/Sourc ## Compatibility -Project building: support for the latest MSVC generation tools and SDKs is mainly considered, and it is generally more widely backward compatible. GCC compatible and can be built with [ReactOS](https://github.com/reactos/reactos). +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](./Source/SlimDetours/SlimDetours.NDK.inl). Can be built with [ReactOS](https://github.com/reactos/reactos). 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 platform. +Runtime environment: NT5 or above OS, x86/x64/ARM64 platforms. > [!CAUTION] > In beta stage, should be used with caution. diff --git a/README.zh-CN.md b/README.zh-CN.md index 1dc1ac5..cd31ac4 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -23,10 +23,10 @@ - 轻量 - **仅依赖`Ntdll.dll`** - 仅保留API挂钩函数 - - 移除对ARM (ARM32)、IA64、WinXP、GNUC的支持 + - 移除对ARM (ARM32)、IA64的支持 - 更小的二进制体积 -- 开箱即用 - - NuGet包发布 + + 以及此处的[待办列表](https://github.com/KNSoft/KNSoft.SlimDetours/milestones?with_issues=no)。 ## 用法 @@ -50,7 +50,15 @@ NuGet包[KNSoft.SlimDetours](https://www.nuget.org/packages/KNSoft.SlimDetours) #pragma comment(lib, "Debug/KNSoft.SlimDetours.lib") ``` -用法与原版[Microsoft Detours](https://github.com/microsoft/Detours)相似，除了： +用法已进行了简化，例如挂钩仅需一行： +```C +SlimDetoursSetHook((PVOID*)&g_pfnXxx, Hooked_Xxx); +``` +更多简化的API参考[Wrapper.c](https://github.com/KNSoft/KNSoft.SlimDetours/blob/main/Source/SlimDetours/Wrapper.c)。 + +### 详细说明 + +原版[Microsoft Detours](https://github.com/microsoft/Detours)风格的函数也有保留，但有少许不同： - 函数名以`"SlimDetours"`开头 - 大多数返回值是用[`HRESULT_FROM_NT`](https://learn.microsoft.com/en-us/windows/win32/api/winerror/nf-winerror-hresult_from_nt)宏包装[`NTSTATUS`](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-erref/87fba13e-bf06-450e-83b1-9241dc81e781)而来的[`HRESULT`](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-erref/0642cb2f-2075-4469-918c-4441e69c548a)，使用类似[`SUCCEEDED`](https://learn.microsoft.com/en-us/windows/win32/api/winerror/nf-winerror-succeeded) 的宏检查它们。 @@ -69,10 +77,6 @@ if (FAILED(hr)) } return SlimDetoursTransactionCommit(); ``` -如果觉得如上Detours风格的API调用复杂，[SlimDetours](https://github.com/KNSoft/KNSoft.SlimDetours)在[Wrapper.c](https://github.com/KNSoft/KNSoft.SlimDetours/blob/main/Source/SlimDetours/Wrapper.c)中提供了一些API，仅需一行即可完成工作，如： -```C -SlimDetoursSetHook((PVOID*)&g_pfnXxx, Hooked_Xxx); -``` ### 延迟挂钩 @@ -91,7 +95,7 @@ SlimDetoursDelayAttach((PVOID*)&g_pfnFuncXxx, ## 兼容性 -项目构建：主要考虑对最新MSVC生成工具及SDK的支持，同时一般也能较广泛地向下兼容。兼容GCC并可随[ReactOS](https://github.com/reactos/reactos)一同构建。 +项目构建：主要考虑对最新MSVC生成工具和SDK的支持。本项目代码能向下兼容MSVC生成工具与GCC，但具体还要看其依赖的NDK，参考[SlimDetours.NDK.inl](./Source/SlimDetours/SlimDetours.NDK.inl)。支持随[ReactOS](https://github.com/reactos/reactos)一同构建。 制品集成：广泛地兼容MSVC生成工具（已知支持VS2015），以及不同编译配置（如`/MD`、`/MT`）。