NativeHook
MonoMod.RuntimeDetour.NativeHook detours a native function, identified by a pointer, to a managed delegate. Like Hook, several NativeHooks on the same function form an ordered chain, and each can call the next one (or the original function) through an orig delegate, if the platform supports it. This page covers the constructors, the delegate shape MonoMod expects, and the CanCallOriginal check.
Example
This is the repository's NativeHookTest, which hooks the C runtime's rand():
using System;
using System.Runtime.InteropServices;
using MonoMod.RuntimeDetour;
using MonoMod.Utils;
public static unsafe class RandDemo
{
[UnmanagedFunctionPointer(CallingConvention.Cdecl)]
private delegate int RandDelegate();
[UnmanagedFunctionPointer(CallingConvention.Cdecl)]
private delegate int RandMixHookDelegate(RandDelegate orig);
private static int RandHook() => -1;
private static int RandMixHook(RandDelegate orig)
{
Console.WriteLine($"original rand() returned {orig()}");
return RandHook();
}
public static void Run()
{
IntPtr libc = DynDll.OpenLibrary(PlatformDetection.OS == OSKind.Windows ? "msvcrt" : "c");
var rand = (delegate* unmanaged[Cdecl]<int>)DynDll.GetExport(libc, "rand");
using (new NativeHook((IntPtr)rand, (RandDelegate)RandHook))
{
Console.WriteLine(rand()); // -1
}
if (NativeHook.CanCallOriginal)
{
using (new NativeHook((IntPtr)rand, (RandMixHookDelegate)RandMixHook))
{
Console.WriteLine(rand()); // prints the original value first, then -1
}
}
}
}
Constructors
public NativeHook(IntPtr function, Delegate hook);
public NativeHook(IntPtr function, Delegate hook, DetourConfig? config);
public NativeHook(IntPtr function, Delegate hook, bool applyByDefault);
public NativeHook(IntPtr function, Delegate hook, DetourConfig? config, bool applyByDefault);
public NativeHook(IntPtr function, Delegate hook, IDetourFactory factory, DetourConfig? config, bool applyByDefault);
| Parameter | Description |
|---|---|
function |
Pointer to the native function to hook (for example from DynDll.GetExport). |
hook |
The managed delegate that runs instead. |
config |
Optional DetourConfig. Defaults to the ambient context's config. |
applyByDefault |
Apply immediately. Default true. |
factory |
Detour engine. Defaults to DetourContext.GetDefaultFactory(). |
The Delegate Shape
MonoMod does not know the native function's signature, so it infers it from your delegate type:
- If the delegate's first parameter is itself a delegate type, and that delegate's parameters equal the remaining parameters of your delegate, MonoMod treats it as the
origparameter. The first parameter's type is then taken as the native signature. - Otherwise, your delegate type itself is taken as the native signature and no
origis passed.
In both cases, put [UnmanagedFunctionPointer] with the correct calling convention on the delegate type that describes the native signature, so that marshalling matches the native code.
Calling the Original: CanCallOriginal
public static bool CanCallOriginal { get; }
Calling the original native function requires the detour engine to build an alternate entry point for it, which not every architecture supports. CanCallOriginal returns DetourContext.GetDefaultFactory().SupportsNativeDetourOrigEntrypoint for the factory ambient on the current thread. If you pass your own factory, check IDetourFactory.SupportsNativeDetourOrigEntrypoint on it instead.
The source's own guidance: even when CanCallOriginal is false, write hooks that accept an orig delegate, and check it for null before calling it. That way hooks from different mods can still coexist in the chain.
Properties and Methods
| Member | Description |
|---|---|
Function |
IntPtr of the hooked function. |
Config |
The DetourConfig? in use. |
IsValid / IsApplied |
Same meaning as on Hook. |
DetourInfo |
A NativeDetourInfo; see Introspection. |
Apply() / Undo() / Dispose() |
Same semantics as Hook, including undo on garbage collection. |
Notes
- Keep the
NativeHookand your delegate alive. The hook object owns the detour; if it is collected, the detour is undone. NativeHooktargets unmanaged code. To hook managed methods, useHook.- Ordering, priorities and
before/afterwork the same way as for managed hooks (Detour Order).