Struct Hook 

pub struct Hook<F: Function = fn()> { /* private fields */ }

A typed function detour, and the RAII guard that owns it.

While enabled, calls to the target run a detour of the same signature F instead; the original stays callable through original. Build one with Hook::at, or Hook::scan to find the target by a byte pattern.

Threads

enable, disable and drop suspend every other thread while patching and move any thread stopped inside the patched bytes, so hooks can be toggled in a running, multi-threaded process. Don’t toggle or drop a hook from inside its own target on the same thread. The unsafe *_unsuspended methods skip the suspension.

Batches

Inside batch, enable and disable are queued and applied together when the batch ends. The *_unsuspended methods apply at once even there, and replace any change queued for the same hook.

Dropping

Dropping a hook disables it and frees its generated code. If it can’t be disabled, say because a third party rewrote the target, the code is leaked instead so the target never jumps into freed memory. leak keeps a hook installed on purpose.

Examples

use imping_hook::Hook;

#[inline(never)]
extern "C" fn add(a: i32, b: i32) -> i32 { a + b }
extern "C" fn sub(a: i32, b: i32) -> i32 { a - b }

// SAFETY: `add` is a real function with the signature below, and `sub`
// shares it.
let hook = unsafe {
    Hook::at(add as *const ())
        .redirect(sub as extern "C" fn(i32, i32) -> i32)
        .install()?
};

assert_eq!(add(3, 2), 5);
hook.enable()?;
assert_eq!(add(3, 2), 1);
assert_eq!(hook.original().call(3, 2), 5);
hook.disable()?;
assert_eq!(add(3, 2), 5);

Implementations

impl Hook

pub fn at(target: *const ()) -> HookBuilder

Starts building a hook of the function at target.

Nothing is patched until install.

pub fn scan(pattern: &str) -> HookScan

Starts building a hook of the function a byte pattern finds.

The pattern is searched for in the main module’s code when the hook is installed, and must match exactly once; see scan for the syntax.

Examples

// SAFETY: the pattern finds a function with the detour's signature.
let hook = unsafe {
    Hook::scan("48 89 5C 24 ?? 57 48 83 EC 20")
        .in_module("engine.dll")
        .redirect(my_detour as extern "C" fn(i32) -> i32)
        .install()?
};

impl<F: Function> Hook<F>

pub fn enable(&self) -> Result<()>

Enables the hook, redirecting the target to the detour.

Does nothing if already enabled. Suspends other threads while patching; see Hook for threads and batches.

Errors

Returns an error naming the target if patching fails, such as Error::TargetModified when a third party changed its code.

pub fn disable(&self) -> Result<()>

Disables the hook, restoring the original function.

Does nothing if already disabled. Suspends other threads while patching; see Hook for threads and batches.

Errors

As for enable.

pub unsafe fn enable_unsuspended(&self) -> Result<()>

Enables the hook without suspending other threads.

Faster than enable, and applied at once even inside a batch; see Hook.

Errors

As for enable.

Safety

No other thread may run the target’s first bytes while they are written, or it may execute a half-written instruction.

pub unsafe fn disable_unsuspended(&self) -> Result<()>

Disables the hook without suspending other threads.

Applied at once like enable_unsuspended.

Errors

As for enable.

Safety

No other thread may run the target’s first bytes while the original ones are written back.

pub fn is_enabled(&self) -> bool

Returns whether the hook is enabled.

pub fn original(&self) -> F::Original<'_>

Returns the original, unhooked function, borrowed from the hook.

Callable whether or not the hook is enabled; see Original.

pub unsafe fn trampoline(&self) -> F

Returns the original function as a pointer not tied to the hook’s lifetime.

Prefer original unless the pointer has to outlive a borrow.

Safety

Don’t call the returned function after the hook is dropped. Use leak if it must stay callable.

pub fn leak(self) -> F

Keeps the hook installed for the rest of the process and returns the original function.

The hook stays in its current state, so enable it first if it should stay active. The target address stays reserved.

Trait Implementations

impl<F: Function> Debug for Hook<F>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<F: Function> Drop for Hook<F>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.