Skip to content

Commit

Permalink
[DOCS] Fix and update documentations
Browse files Browse the repository at this point in the history
  • Loading branch information
RatinCN committed Aug 9, 2024
1 parent eb248b3 commit 4a8c5da
Show file tree
Hide file tree
Showing 3 changed files with 29 additions and 21 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
24 changes: 14 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.
Expand All @@ -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

Expand All @@ -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.
Expand Down
22 changes: 13 additions & 9 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

## 用法

Expand All @@ -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) 的宏检查它们。
Expand All @@ -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);
```

### 延迟挂钩

Expand All @@ -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`)。
Expand Down

0 comments on commit 4a8c5da

Please sign in to comment.