Documentation draft

[akriegman]

If I'm not mistaken there's no API documentation for Interception, which would be really helpful to have. I asked ChatGPT to write some documentation and I think it did a decent job. Maybe someone who knows the library well wants check this for correctness and completeness and then make it the official documentation? Thanks!

Interception Library Documentation

Overview

The Interception library provides an interface for capturing and processing keyboard and mouse input at a low level on Windows. It allows applications to intercept, filter, and modify input events before they reach their intended destinations.

API Reference

1. Structs

1.1 InterceptionKeyStroke

Represents a keyboard input event.

Members:

• unsigned short code: The key code of the keyboard event.
• unsigned short state: The state of the key (e.g., key down or key up).

1.2 InterceptionMouseStroke

Represents a mouse input event.

Members:

• unsigned short state: The state of the mouse buttons.
• unsigned short flags: Flags representing additional state information.
• short rolling: The rolling delta for mouse wheel events.
• int x: The x-coordinate of the mouse cursor.
• int y: The y-coordinate of the mouse cursor.
• unsigned int information: Additional information about the mouse event.

1.3 InterceptionStroke

A union representing an input event (either keyboard or mouse).

Members:

• InterceptionKeyStroke key: Represents a keyboard input event.
• InterceptionMouseStroke mouse: Represents a mouse input event.

2. Enums and Constants

2.1 Key States

Constants for state in InterceptionKeyStroke:

• INTERCEPTION_KEY_DOWN
• INTERCEPTION_KEY_UP
• INTERCEPTION_KEY_E0
• INTERCEPTION_KEY_E1
• INTERCEPTION_KEY_TERMSRV_SET_LED
• INTERCEPTION_KEY_TERMSRV_SHADOW

2.2 Mouse States

Constants for state in InterceptionMouseStroke:

• INTERCEPTION_MOUSE_LEFT_BUTTON_DOWN
• INTERCEPTION_MOUSE_LEFT_BUTTON_UP
• INTERCEPTION_MOUSE_RIGHT_BUTTON_DOWN
• INTERCEPTION_MOUSE_RIGHT_BUTTON_UP
• INTERCEPTION_MOUSE_MIDDLE_BUTTON_DOWN
• INTERCEPTION_MOUSE_MIDDLE_BUTTON_UP
• INTERCEPTION_MOUSE_BUTTON_4_DOWN
• INTERCEPTION_MOUSE_BUTTON_4_UP
• INTERCEPTION_MOUSE_BUTTON_5_DOWN
• INTERCEPTION_MOUSE_BUTTON_5_UP
• INTERCEPTION_MOUSE_WHEEL
• INTERCEPTION_MOUSE_HWHEEL

2.3 Mouse Flags

Constants for flags in InterceptionMouseStroke:

• INTERCEPTION_MOUSE_MOVE_RELATIVE
• INTERCEPTION_MOUSE_MOVE_ABSOLUTE
• INTERCEPTION_MOUSE_VIRTUAL_DESKTOP
• INTERCEPTION_MOUSE_ATTRIBUTES_CHANGED

3. Functions

3.1 Context Management

• InterceptionContext interception_create_context(void);

  • Creates and initializes a new Interception context.
  • Returns: A handle to the newly created context.
  • Notes: Must be destroyed using interception_destroy_context.

• void interception_destroy_context(InterceptionContext context);

  • Destroys an Interception context and releases its resources.
  • Parameters:
    • context: The Interception context to be destroyed.

3.2 Device Management

• InterceptionDevice interception_wait(InterceptionContext context);

  • Waits for the next input event from any device.
  • Parameters:
    • context: The Interception context.
  • Returns: A handle to the device that generated the event.

• int interception_receive(InterceptionContext context, InterceptionDevice device, InterceptionStroke *stroke, unsigned int nstroke);

  • Receives input events from a specified device.
  • Parameters:
    • context: The Interception context.
    • device: The device handle.
    • stroke: Pointer to an array of InterceptionStroke structures to receive the events.
    • nstroke: The number of strokes to receive.
  • Returns: The number of strokes received.

• int interception_send(InterceptionContext context, InterceptionDevice device, const InterceptionStroke *stroke, unsigned int nstroke);

  • Sends input events to a specified device.
  • Parameters:
    • context: The Interception context.
    • device: The device handle.
    • stroke: Pointer to an array of InterceptionStroke structures containing the events to send.
    • nstroke: The number of strokes to send.
  • Returns: The number of strokes sent.

• unsigned int interception_get_hardware_id(InterceptionContext context, InterceptionDevice device, void *buffer, unsigned int buffer_size);

  • Retrieves the hardware ID of a specified device.
  • Parameters:
    • context: The Interception context.
    • device: The device handle.
    • buffer: Pointer to a buffer to receive the hardware ID.
    • buffer_size: The size of the buffer.
  • Returns: The size of the hardware ID string.

3.3 Filter Management

• void interception_set_filter(InterceptionContext context, InterceptionPredicate predicate, InterceptionFilter filter);

  • Sets a filter for devices matching the given predicate.
  • Parameters:
    • context: The Interception context.
    • predicate: A function pointer to a predicate function to match devices.
    • filter: The filter to apply to matching devices.

• InterceptionFilter interception_get_filter(InterceptionContext context, InterceptionDevice device);

  • Retrieves the current filter for a specified device.
  • Parameters:
    • context: The Interception context.
    • device: The device handle.
  • Returns: The current filter for the specified device.

3.4 Predicate Functions

• int interception_is_keyboard(InterceptionDevice device);

  • Checks if the device is a keyboard.
  • Parameters:
    • device: The device handle.
  • Returns: Non-zero if the device is a keyboard, zero otherwise.

• int interception_is_mouse(InterceptionDevice device);

  • Checks if the device is a mouse.
  • Parameters:
    • device: The device handle.
  • Returns: Non-zero if the device is a mouse, zero otherwise.

Example Usage

#include <iostream>
#include <windows.h>
#include "interception.h"

void process_key_event(InterceptionKeyStroke& stroke) {
    std::cout << "Key event: code = " << stroke.code
              << ", state = " << stroke.state << std::endl;
}

int main() {
    InterceptionContext context;
    InterceptionDevice device;
    InterceptionStroke stroke;

    context = interception_create_context();

    interception_set_filter(context, interception_is_keyboard, INTERCEPTION_FILTER_KEY_DOWN | INTERCEPTION_FILTER_KEY_UP);

    while (interception_receive(context, device = interception_wait(context), &stroke, 1) > 0) {
        if (interception_is_keyboard(device)) {
            InterceptionKeyStroke& keyStroke = *(InterceptionKeyStroke*)&stroke;
            
            // Process key event
            process_key_event(keyStroke);

            // Continue sending the stroke to the OS
            interception_send(context, device, &stroke, 1);
        }
    }

    interception_destroy_context(context);

    return 0;
}

Notes:

• Ensure that the device ID used for filtering matches the specific keyboard or mouse you want to intercept.
• The Interception library operates at a low level and may require administrative privileges.
• Some special keys may require additional handling based on their unique key codes or state information.

[Kyr27]

Looks excellent, ChatGPT is crazy good now, given enough information.
This is something that should be added to the project wiki, as this is something i wish i saw right away(and others surely will too).
You should also consider making a pull request and adding it to the interception header file, e.g.,

/**
 * @brief Calculates the factorial of a number.
 *
 * This function computes the factorial of a non-negative integer using
 * an iterative approach.
 *
 * @param n The non-negative integer for which the factorial is to be computed.
 *          Must be >= 0.
 *
 * @return The factorial of the given number. Returns 1 if n is 0.
 *
 * @note This function does not handle negative inputs. Ensure n is non-negative.
 */

int factorial(int n);

Unfortunately it does not seem like @oblitum is active on GitHub anymore, so it's unknown whether the pull request would be accepted or not.