Hook

Install a detour on a function using MinHook. Maximum 32 simultaneous hooks per environment.

Syntax

Susano.Memory.Hook(address, signature, callback) -> integer

Parameters

address (integer): Target function address.

signature (string): Same format as Call: "<return>:<args>".

callback (function): Called on every invocation of the hooked function. Receives three closures:

get(argIndex): read argument N (1-indexed). Returns a value typed according to the signature.
set(argIndex, value): modify argument N (1-indexed) before calling the original.
call(): call the original function with the current (possibly modified) arguments and return its return value.

Callback return value:

Return nil (or nothing): the original function runs normally with the (possibly modified) args.
Return <value>: the original is skipped, and this value is returned to the caller instead.

Return(s)

integer: Hook slot ID (0-31), used with Unhook.

Behavior

All hooks owned by a Lua environment are automatically removed when that environment is destroyed.

Example(s)

local hookId = Susano.Memory.Hook(targetAddr, "l:pif", function(get, set, call)
    local arg1 = get(1)   -- pointer
    local arg2 = get(2)   -- int
    local arg3 = get(3)   -- float

    -- modify arg 2 before the original runs
    set(2, arg2 + 1)

    -- call the original
    local ret = call()

    -- return nil to pass through, or a value to override the caller's return
    return ret
end)