kthook

X86 hooking library with functor callbacks support, so you can use lambdas with state, std::bind values etc...

Usage

Clone repository and simply include kthook.hpp. C++17 compatible compiler required

Examples

Callbacks backend is ktsignal

All hooks are automatically removed in the kthook destructor

All examples are shown based on this function

int FASTCALL func1(float a, float b) {
    print_info(a, b);
    a = 50; b = 100;
    return 5;
}

Basics

Creating hook and binding callback
All callbacks are given a reference to kthook as the first argument. You can get return address and trampoline pointer from hook object.
Hooks are installed after construction by default(last parameter can be set to false to prevent this)

int main() {
    // func_ptr is pointer to function
    auto func_ptr = &func1;

    // func_type is int(CFASTCALL*)(float, float)
    using func_type = decltype(&func1);

    // Creating simple hook object with function type is template parameter and function pointer in constructor
    kthook::kthook_simple<func_type> hook{ func_ptr };

    // Connecting lambda callback that receiving function arguments by references
    hook.before += [](const auto& hook, float& a, float& b) {
        print_info(a, b);
        return std::nullopt;
    };

    /*
    [operator () at 31]: a = 30; b = 20
    [func1 at 16 ]: a = 30; b = 20
    */
    func1(30.f, 20.f);
}

Same thing with common hooks:

int main() {
    // func_ptr is pointer to function
    auto func_ptr = &func1;

    // func_type is int(CFASTCALL*)(float, float)
    using func_type = decltype(&func1);

    auto cb = [](const auto& hook, float a, float b) {
        print_info(a, b);
        return hook.get_trampoline()(a, b);
    };

    // Creating simple hook object with function type is template parameter and function pointer in constructor
    kthook::kthook_simple<func_type> hook{ func_ptr, cb };

    /*
    [operator () at 31]: a = 30; b = 20
    [func1 at 16 ]: a = 30; b = 20
    */
    func1(30.f, 20.f);
}

Also you can bind after original function execution callbacks
If original function return value is non void, return value reference passed at 2 argument

int main() {
    auto func_ptr = &func1;
    using func_type = decltype(&func1);

    kthook::kthook_simple_t<func_type> hook{ func_ptr };

    hook.before.connect([](const auto& hook, float& a, float& b) { 
        print_info(a, b);
        // changing arguments
        a = 50.f, b = 30.f; 
        return std::nullopt;
        });

    // connect after callback
    hook.after.connect([](const auto& hook, int& return_value, float& a, float& b) {
        print_info(a, b);
        print_return_value(return_value);

        // changing return_value
        return_value = 20;
    });

    /*
    [operator () at 31]: a = 30; b = 20
    [func1 at 16 ]: a = 50; b = 30
    [operator () at 34]: a = 50; b = 30
    [operator () at 34]: return_value = 5;
    [main at 20]: return_value = 20;
    */
    auto ret_val = func1(30.f, 20.f);
    print_return_value(ret_val)
}

You can bind multiple before/after callbacks

int main() {
    auto func_ptr = &func1;
    using func_type = decltype(&func1);

    kthook::kthook_simple_t<func_type> hook{ func_ptr };

    hook.before.connect([](const auto& hook, float& a, float& b) { print_info(a, b); return std::nullopt; });
    hook.before.connect([](const auto& hook, float& a, float& b) { a = 20; b = 30; return std::nullopt; });
    hook.after.connect([](const auto& hook, int& ret_val, float& a, float& b) { print_info(a, b); });
    hook.after.connect([](const auto& hook, int& ret_val, float& a, float& b) { print_info(a, b); });
    /*
    [operator () at 31]: a = 0; b = 0
    [func1 at 16]: a = 20; b = 30
    [operator () at 33]: a = 20; b = 30
    [operator () at 34]: a = 20; b = 30
    [main at 20]: return_value = 5;
    */
    auto ret_val = func1(30.f, 20.f);
    print_return_value(ret_val)
}

important notes

• Function return type must be default-constructible
• If any before callback wiil return false, and function return type is non void, the original function and after callback are not called. Default constructed value is returned
• If all before callbacks will return true, original function and after callbacks will be called

Advanced Usage

There is a kthook that allows you to change the return value from a function without calling the original function
For generating true return value, you can use std::make_optional(value) function
For generating false return value, you can use std::nullopt

If function return type is void, then you can just return true/false see notes

int main() {
    auto func_ptr = &func1;
    using func_type = decltype(&func1);

    kthook::kthook_signal<func_type> hook{ func_ptr };
    
    hook.before.connect([](const auto& hook, float& a, float& b) { print_info(a, b); return std::nullopt; });
    hook.after.connect([](const auto& hook, int& ret_val, float& a, float& b) { ret_val = 20; print_info(a, b); });
    /*
    [operator () at 44]: a = 30; b = 20
    [func1 at 16]: a = 30; b = 20
    [operator () at 45]: a = 30; b = 20
    [main at 20]: return_value = 20;
    */
    auto ret_val = func1(30.f, 20.f);
    print_return_value(ret_val)
}

Return false example

int main() {
    auto func_ptr = &func1;
    using func_type = decltype(&func1);

    kthook::kthook_signal<func_type> hook{ func_ptr };
    
    hook.before.connect([](auto& hook, float& a, float& b) { print_info(a, b); return std::make_optional(20); });
    hook.after.connect([](auto& hook, int& ret_val, float& a, float& b) { ret_val = 20; print_info(a, b); });
    /*
    [operator () at 44]: a = 30; b = 20
    [main at 20]: return_value = 20;
    */
    auto ret_val = func1(30.f, 20.f);
    print_return_value(ret_val)
}

More examples can be found here

Credits

xbyak - x86/x86-64 JIT assembler
ktsignal - C++17 signals library

License

kthook is licensed under the MIT License, see LICENSE.txt for more information.