You are here: Home

LGS Debug Interceptor

LGS Debug Interceptor (LGSDI) is a 64-bit (x64) DLL that delivers Logitech Gaming Software (LGS) Lua script OutputDebugMessage() strings. It can be used by third-party applications to extend the capabilities of LGS scripts; eg, by displaying additional information or interacting with other hardware.

LGSDI should be usable with any programming language or environment that can call functions in 64-bit Windows DLLs. COM is not required. The download file includes examples for AutoHotKey and C# WPF.

Because LGSDI hooks LGS for debugging, it obtains direct and immediate access to these strings, so polling is not required. This reduces latency and CPU usage.

Warnings

You use this at your own risk.

To obtain OutputDebugMessage strings directly, LGSDI hooks LGS for debugging. This is fairly savage on LGS and can crash it if misused. To minimise the risk of this, return from LGSDK callback functions (if used) as quickly as possible, ensure you call LGSDIDisconnect() when finished, and keep your callback functions (if used) available until notified of disconnection.

Some malware uses debug hooking to inspect and alter memory associated with other processes. While LGSSDI doesn't do this, some anti-virus products may suspect LGSDI because it uses some of the same API calls.

LGSDI only works on Windows x64. It has only been tested on Windows 7 with LGS 8.70.315, a G19s keyboard and a G500s mouse. However, it should work on any 64-bit Windows with any version of LGS that supports OutputDebugMessage() in Lua scripts.

Any program that uses LGSDI may need to be run with administrator privileges. Or maybe not. I don't know.

Usage Options

There are four different ways of using LGS, which differ in terms of the means by which your application is notified of events from LGSDI.

Callback Functions (Asynchronous)

You must implement two functions that LGSDI will call to communicate information to your application.

The use of callback functions maximises performance, since it avoids use of the Windows message queue.

The callback functions will NOT be called on the same thread from which the LGSDI connection was established. If you need to interact with the Windows UI, thread marshalling will be required. You may be able to do this by sending Windows messages to your main window's message queue; most modern programming environments provide convenient functions for this (eg, WPF's Invoke()).

Your application will remain responsive even if you establish an asynchronous connection from the UI thread.

Callback Functions (Synchronous)

You must implement two functions that LGSDI will call to communicate information to your application.

The use of callback functions maximises performance, since it avoids use of the Windows message queue.

The callback functions will be called on the same thread from which the LGSDI connection was established. If this is the UI thread, thread marshalling will not be required for interaction with the UI. However...

If you establish a synchronous connection on the UI thread, your application will be unresponsive. Therefore, use this option only on a background thread.

Windows Messages sent to a Specific Window

The window to which messages should be sent must be specified by its handle (HWND). You need to monitor the Windows message queue to detect messages from LGSDI.

Windows normally marshalls messages onto the UI thread, so this simplifies UI interaction (since only the UI thread should interact with the UI).

If your application is multi-threaded, you may not want to burden your UI thread with LGSDI notifications. In this case, consider using callback functions.

Windows Messages sent to a Specific Thread

The thread to which Windows messages should be sent must be specified by its ID (or zero to use the current thread). The thread must have a message queue for this to work. You need to monitor the Windows message queue to detect messages from LGSDI.

In a single-threaded application, the current thread will be that of the main window, making this option easy to implement.

In some environments (eg, WPF), identifying Win32 thread IDs that have message queues is difficult.

If your application is multi-threaded, you will get better performance and control by using callback functions.

Flow of Control

Your host program may be statically linked to "LGS Debug Interceptor.dll", or may access it dynamically at runtime.

The host program calls one of the LGSDIConnect...() functions, passing parameters needed for LGSDI to communicate events back to the program.

LGSDI receives events from LGS (usually Lua script OutputDebugMessage() strings), which it passes to the host program.

The host program can do whatever it likes on the basis of the messages received. Options include displaying images or web pages, writing to a keyboard's LCD, playing sounds, etc.

When finished, the host program must tell LGSDI to disconnect. This can be done via a callback function return value, or by calling LGSDIDisconnect() (except if a synchronous connection is in place).

Download

Download the installation file here:

If your anti-virus software complains, you may need to disable it (reason).

Documentation

In addition to the DLL, the download file contains documentation on LGSDI's exported functions and data types.

The download file also contains AutoHotKey scripts that demonstrate all four usage options, and C# WPF code that demonstrates the use of asynchronous callback functions and Windows messages.

Support

You can contact Gondwana Software here. Alternatively, try the Logitech ‘Scripting and SDK’ forum.