User Plugin for Filtering Serial Port Splitter Data

General description

There is a possibility to use a user-written plugin to filter data that comes from application to physical port. It works for split and joined configurations.

Application → virtual COM port → [custom plugin] → physical COM port

In order to enable this feature it's needed to place DLL library of special format (described below) into the following folder: SYSTEMROOT\SYSTEM32 (for 32-bit OS) SYSTEMROOT\SYSWOW64 (for 64-bit OS). The name of dll should be filter.dll. The plugin allows to manipulate data (modify/insert/remove) sent by application. In case if there is no specified DLL, no data manipulation will be performed.

Exported functions

Init

Initialization of filtering for specified COM port. This function is called by the program for each split or joined physical COM port.

BOOL __cdecl Init(
        wchar_t *lpszPortName,
        UINT lpdwPortId,
        LPFNPLUGIN_WRITEDATA_CALLBACK lpfnWriteData);

Parameters:

[in] lpszPortName - COM port name in format "COMx"

[in] lpdwPortId - unique COM port id that will be used later in callback.

[in] lpfnWriteData - callback function for writing data to COM port. Modified data should be transferred there in order to be written to physical COM port.

Return value:

TRUE - if operation was successful.

Remarks:

The DLL should store all *lpdwPortId* values and corresponding *lpfnWriteData* values.

ProceedData

Processing of data that application intends to write to COM port.

It's possible to analyze, store, modify, skip some data or write it to destination COM port (by calling the corresponding callback function).

BOOL __cdecl ProceedData(
        UINT dwPortId,
        const void* lpBuffer,
        UINT lpcbBuffer);

Parameters:

[in] dwPortId - unique COM port id (refer to Init function). This ID specifies COM port where data is writing.

[in] lpBuffer - pointer to data buffer.

[in] lpcbBuffer - size of lpBuffer.

Return value:

TRUE - if operation was successful.

FALSE - data will be transferred to destination physical COM port without any modifications.

Remarks:

Modified data should be written to needed physical COM port using corresponding *lpfnWriteData*.

The DLL will not obtain new data until *ProceedData* return.

If no data modification is needed, you should return FALSE or call *lpfnWriteData* with unmodified source data.

Cleanup

De-init filtering DLL for specified COM port.

BOOL __cdecl Cleanup(UINT dwPortId);

Parameters:

[in] dwPortId - unique COM port id (refer to Init function).

Return value:

Always return TRUE.

Remarks:

This function is called when the COM port is not split (joined) anymore.

Potential memory leaks and other problems

Author of DLL is responsible for releasing memory that was allocated inside the plugin.

In case if incorrect operation of the plugin (errors while working with memory, errors of resources allocation, errors with threads, etc), the product service can crash, and the following service restart (or even computer reboot) will be needed.

31 March 2023