SharpHook

If you need to implement a hook that does not follow the IGlobalHook interface (for example, if you are implementing IReactiveGlobalHook or IR3GlobalHook), you should extend BasicGlobalHookBase instead of GlobalHookBase.

BasicGlobalHookBase is the root implementation for the SharpHook hierarchy. It provides the core logic for IBasicGlobalHook (which defines Run, RunAsync, Stop, IsRunning, and IsDisposed) and handles the non-trivial event-handling machinery.

By extending BasicGlobalHookBase, you gain access to HandleHookEvent, BeforeRun, AfterStop, and Dispose without having to implement the underlying provider logic yourself.

public sealed class StraightforwardGlobalHook : BasicGlobalHookBase
{
    protected override void HandleHookEvent(ref UioHookEvent e) =>
        this.HookEvent?.Invoke(this, e);

    public event EventHandler<UioHookEvent>? HookEvent;
}

SharpHook provides three implementations of IGlobalHook, each with different threading models for handling events:

Configuring Hook Types

You can create a keyboard-only or mouse-only hook by passing a GlobalHookType to the constructor.

• Windows: This utilizes the OS-specific distinction between keyboard and mouse hooks.
• macOS/Linux: This simply enables filtering of the respective event types.

A Global Hook allows you to monitor and intercept system-wide keyboard and mouse events. SharpHook provides the IGlobalHook interface with three primary implementations, each with different threading models:

1. SimpleGlobalHook: Runs all event handlers on the same thread as the hook. Handlers must be extremely fast to avoid blocking the hook from processing subsequent events.
2. EventLoopGlobalHook: Runs event handlers on a dedicated separate thread. It queues events if backpressure occurs, ensuring no events are lost. Note: Because handlers run on a different thread, suppressing event propagation (setting SuppressEvent = true) is not supported.
3. TaskPoolGlobalHook: Runs event handlers in parallel using the default .NET task pool. Like the event loop implementation, it queues events on backpressure, but suppressing event propagation is not supported.

Critical Constraints:

• Single Instance Rule: You must use only one IGlobalHook instance at a time in your entire application. Multiple instances will attempt to use the same underlying callback in libuiohook, leading to corruption of the internal global state.
• Lifecycle: IGlobalHook implements IDisposable. Calling Dispose stops the hook and prevents it from being restarted. You must create a new instance to start a hook again after disposal.

// Example of using EventLoopGlobalHook
var hook = new EventLoopGlobalHook();

hook.KeyPressed += (s, e) => Console.WriteLine($"Key pressed: {e.Key}");

hook.Run(); // Blocks current thread
// OR
await hook.RunAsync(); // Runs on separate thread

Both IReactiveGlobalHook (Rx.NET) and IR3GlobalHook (R3) follow these lifecycle rules and constraints:

Critical Constraint: Singleton Usage

Always use only one instance of a reactive global hook at a time in your entire application. Because all hooks must use the same static method to set the callback for libuiohook, running multiple hooks simultaneously will corrupt the internal global state of libuiohook.

Lifecycle Methods

• Run() / RunAsync(): Starts the hook. Running the hook while it is already running is not allowed. Check IsRunning to verify state.
• Stop(): Stops the running hook.
• Dispose(): Disposes of the hook and stops it if it is running. All observables will complete upon disposal. Once disposed, the instance cannot be started again. Check IsDisposed to verify state.

Observables

All observables emit EventArgs-derived types. When the hook is disposed, all active observables will complete.