TrafficMonitor Administrator & Developer Guide

This guide is the exhaustive technical reference for TrafficMonitor — a native Windows desktop network/hardware monitor written in C++ with the MFC framework. It is intended for power users, IT administrators who deploy it across machines, skin and plugin developers, and anyone who needs to understand, build, configure, or extend the application from source.

Where the User Guide explains how to use TrafficMonitor, this guide explains how it is built, where it stores state, every setting it persists, how to compile it, and how to extend it.

1. Executive Summary

Design in one sentence: a single‑instance MFC dialog application that samples network and hardware counters on a timer, renders the results into a floating window and/or a window embedded in the Windows taskbar, and persists all user choices to INI files located either beside the executable (portable mode) or in %AppData%.

Note

TrafficMonitor has no command‑line interface, no network server, no API, and no telemetry. Its only outbound network activity is an optional update check against GitHub or Gitee. All "configuration" is performed through the GUI and serialized to INI files documented in Section 5.

2. Architecture

2.1 High‑level structure

                     +--------------------------------------------------+
                     |              CTrafficMonitorApp (CWinApp)         |
                     |  - InitInstance(): single-instance mutex,         |
                     |    path resolution, plugin load, config load      |
                     |  - LoadConfig()/SaveConfig(): INI <-> structs      |
                     |  - Update check thread, hardware-init thread       |
                     +-------------------------+------------------------+
                                               |
                          +--------------------+--------------------+
                          |                                         |
              +-----------v-----------+               +-------------v------------+
              | CTrafficMonitorDlg     |               |  Worker threads          |
              | (main floating window) |               |  - MonitorThreadCallback |
              |  - OnTimer sampling    |               |  - CheckUpdateThreadFunc |
              |  - right-click menu     |               |  - InitOpenHardwareLib   |
              |  - notify (tray) icon  |               +-------------+------------+
              |  - hosts CTaskBarDlg   |                             |
              +-----------+-----------+               +-------------v------------+
                          |                            |  Data acquisition layer  |
          +---------------+--------------+             |  - iphlpapi (net speed)  |
          |               |              |             |  - PdhHardwareQuery      |
   +------v-----+  +------v------+ +-----v------+      |    (CPU/GPU/disk/freq)   |
   | CTaskBarDlg|  | CSkinFile   | | PluginMgr  |      |  - OpenHardwareMonitorApi|
   | (taskbar   |  | CSkinManager| | (ITMPlugin)|      |    (temperatures, .NET)  |
   |  window)   |  +-------------+ +------------+      +--------------------------+
   +-----+------+
         |
   +-----v-----------------------------+
   | Rendering backends (factory)      |
   |  - GDI / GDI+ (DrawCommon)         |
   |  - Direct2D / DComposition (D2D1)  |
   +-----------------------------------+

2.2 Component inventory

The codebase is organized into one main application project plus several helper projects. Key modules:

2.3 Threading model

TrafficMonitor is predominantly single‑threaded (MFC message pump) with a few dedicated worker threads to keep the UI responsive:

Note

The monitor thread communicates results back to the UI via a posted message (OnMonitorInfoUpdated) and the m_monitor_data_required flag, with a CEvent (m_threadExitEvent) used to coordinate clean shutdown.

2.4 Rendering backends

Drawing is abstracted behind a factory (DrawCommonFactory / IDrawCommon) so the taskbar window can render with either GDI/GDI+ or Direct2D (with DirectComposition for layered transparency). Direct2D was added in v1.85 to fix jagged font edges and HDR/transparency issues; it can be toggled with the disable_d2d setting.

3. System Requirements

Important

The Standard version checks for .NET Framework 4.5 at startup (IsDotNetFramework4Point5Installed) and warns if it is missing. The Lite version (built with WITHOUT_TEMPERATURE) skips this check entirely.

4. Installation & Deployment

4.1 Standard deployment

TrafficMonitor is portable. To deploy:

1. Extract the release ZIP to a target folder.
2. Decide the data location strategy (see 4.2).
3. Launch TrafficMonitor.exe.

4.2 Portable mode vs AppData

At startup, LoadGlobalConfig() decides where settings are stored:

global_cfg.ini exists?
  ├─ yes → read [config] portable_mode
  └─ no  → portable_mode defaults to:
             (config.ini already in %AppData%? → false : true)

Then InitInstance():
  if portable_mode → config_dir = <program folder>
  else             → config_dir = %AppData%\Roaming\TrafficMonitor\

Hard override: if the program folder is NOT writable, OR the program is
running from a Temp directory → portable_mode forced to false (use AppData).

global_cfg.ini (in the program folder) controls the switch:

[config]
portable_mode = false

Tip

For multi‑user machines or installs under C:\Program Files\, set portable_mode = false so each user gets their own settings under their profile and write‑permission errors are avoided.

4.3 Files written at runtime

4.4 Mass deployment notes

• To pre‑seed settings across machines, distribute a prepared config.ini alongside the executable and set portable_mode = true, or drop the config.ini into each user's %AppData%\Roaming\TrafficMonitor\.
• Autostart is per‑user (HKCU registry or a per‑user scheduled task), so it must be configured in each user's session, not machine‑wide.

5. Configuration Reference

All settings live in config.ini and are loaded/saved by CTrafficMonitorApp::LoadConfig() / SaveConfig(). The file is organized into the sections below. These keys, types, and defaults are taken directly from the source and represent the authoritative configuration reference.

Caution

Editing config.ini by hand is supported but unusual — the GUI is the intended interface. If you do edit it, close TrafficMonitor first, because SaveConfig() rewrites the whole file on exit and will overwrite your changes.

5.1 [general] — General settings

5.2 [config] — Main window & general toggles

5.3 [connection] — Network adapter selection

5.4 [skins] — Skin auto‑adaptation

5.5 [task_bar] — Taskbar window settings

The taskbar window has its own complete set of appearance and behavior settings.

5.6 [notify_tip] — Notification thresholds

Each threshold has an _enable bool and a _value int.

5.7 [histroy_traffic] — History view (note: key is spelled "histroy" in code)

5.8 [other] — Advanced/internal

5.9 [app] — Bookkeeping

Note

Several keys are deliberately not in config.ini: the main window's text colors, fonts, and display text are saved per‑skin (in each skin's settings) rather than globally — see the comments in LoadConfig().

6. Operations

6.1 Autostart management

TrafficMonitor supports two autostart mechanisms (SetAutoRun(auto_run, task_scheduler)):

GetAutoRun() compares the stored path to the current m_module_path_reg:
  - registry value present AND equals current exe path → autostart active
  - otherwise → inactive (stale path = broken autostart)

Important

Moving the program folder invalidates autostart because the stored path no longer matches. The Task Scheduler approach exists specifically because the registry method fails when the app needs to run elevated. Switching between Standard and Lite migrates the autostart entry from one mechanism to the other automatically.

Warning

Registry‑based autostart does not work when "Run as administrator" is set on the executable, because the Run key launches non‑elevated. Use the Task Scheduler method (Standard version) for elevated autostart.

6.2 Single‑instance enforcement

InitInstance() creates a named mutex (TrafficMonitor-1419J3XLKL1w8OZc in release builds). If it already exists, the new process finds the existing window via FindWindow(APP_CLASS_NAME), shows the "already running" dialog, and exits. Suppress the dialog with [other] no_multistart_warning = true.

6.3 Update checking

At startup (and on demand), CheckUpdate() queries the configured update source:

• update_source = 0 → GitHub
• update_source = 1 → Gitee (default for Simplified Chinese, since GitHub is often blocked in mainland China)

It selects a per‑architecture download link (GetLink64 / GetLinkArm64ec / GetLink) and compares the remote version string to the compiled VERSION. Plugin updates are checked in the same background thread via m_plugin_update.CheckForUpdate().

6.4 Logs & crash reports

• crashtool installs a crash handler (CRASHREPORT::StartCrashReport()) that, since v1.86, displays the call stack and writes crash information to a log file.
• Enable verbose logging with [other] debug_log = true; output goes to error.log in config_dir.

6.5 Backup & restore

• Settings: copy config.ini from config_dir.
• History: copy history_traffic.dat (and .bak). The app keeps a .bak backup and can restore from it (BackupHistoryTrafficFile / restore logic in HistoryTrafficFile).
• To migrate a user to a new machine, copy both files into the same config_dir (portable folder or %AppData%\Roaming\TrafficMonitor\).

7. Security Analysis

Note

This section is an objective security review of an open‑source desktop utility, intended to help administrators make deployment decisions. TrafficMonitor is a legitimate monitoring tool with no malicious behavior identified in source.

7.1 Privilege model

• The Lite version runs with standard user rights.
• The Standard version requires administrator privileges to read hardware sensors via LibreHardwareMonitor, which loads a kernel driver (LibreHardwareMonitorLib.sys) for low‑level hardware access.

Caution

The bundled LibreHardwareMonitorLib.dll and its kernel driver are a third‑party component with deep hardware access. Some endpoint‑security products (e.g. Huorong, per issue reports) flag or block the driver. This is the highest‑privilege surface in the application. If you do not need temperatures, deploy the Lite version to avoid loading the driver entirely.

7.2 Attack surface

Warning

The plugin system is the primary trust boundary. Because plugins are unsigned native DLLs loaded by file presence in plugins\, only deploy plugins from trusted sources. In managed environments, consider locking down write access to the plugins\ directory.

7.3 Data privacy

• All monitoring data and history stay local in flat files. No data is transmitted.
• The "Contact Author" feature opens the user's mail client; it does not auto‑send anything.

7.4 Hardening recommendations

• [ ] Deploy the Lite version unless temperatures are required (removes the kernel driver).
• [ ] Run as a standard user (avoid elevation) where possible.
• [ ] Restrict write permissions on the plugins\ and skins\ folders in shared environments.
• [ ] Set portable_mode = false so per‑user data lives under each profile.
• [ ] Keep the program updated (it self‑checks; or push updates centrally).

8. Building From Source

8.1 Toolchain

8.2 Solution files

8.3 Build steps

1. Open TrafficMonitor.sln (or TrafficMonitor_Lite.sln) in Visual Studio.
2. Select configuration (Debug/Release) and platform (x64 / Win32 / ARM64EC).
3. Build Solution.
4. Output: TrafficMonitor.exe in the configuration's output folder,
   with skins\ and language\ copied alongside.

8.4 Important compile‑time defines

8.5 Project layout

TrafficMonitor/            Main application (179 source files)
  PdhHardwareQuery/        Performance-counter wrappers (CPU/GPU/disk/freq)
  language/                15 localization .ini files
  skins/                   Bundled skins (skin.ini/skin.xml + backgrounds)
  res/                     Icons and bitmaps
  tinyxml2/                Vendored XML parser
OpenHardwareMonitorApi/    C++/CLI bridge to LibreHardwareMonitor (temperature)
  LibreHardwareMonitorLib.dll   Bundled .NET hardware library
include/
  PluginInterface.h        Public plugin ABI
  OpenHardwareMonitor/     OpenHardwareMonitor API headers
PluginDemo/                Example plugin project

9. Plugin Development Reference

Plugins are native C++ DLLs placed in plugins\ next to the executable. They are discovered and loaded at startup by CPluginManager. A plugin DLL must export a single C function:

// Returns a pointer to a single, long-lived ITMPlugin object
// (usually a global/static). It must not be freed before program exit.
ITMPlugin* TMPluginGetInstance();

9.1 Interfaces

The plugin ABI is declared in include/PluginInterface.h. Current API version: 7.

9.2 ITMPlugin (implement this)

9.3 IPluginItem (one per display item)

9.4 ITrafficMonitor (host interface, provided to you)

Tip

Cache data in DataRequired() and simply return cached values from GetItemValueText() — that getter is called frequently for layout and must be cheap. This guidance is stated directly in the interface header.

9.5 API version history (ABI evolution)

A reference implementation is provided in the PluginDemo project (items for system date/time plus a custom‑drawn item).

10. Skin Format Reference

Skins live in skins\<SkinName>\ and theme the floating window only. A skin folder contains:

Important

A skin that ships only skin.ini cannot render temperature/GPU items. Skin authors should provide skin.xml. Parsing is handled by CSkinFile using the vendored tinyxml2 for XML and IniHelper for INI.

See the project's skin‑making tutorial (皮肤制作教程.md / Wiki) for the full field reference.

11. Localization

The UI is fully externalized into .ini language files under TrafficMonitor/language/. Supported languages:

English, Simplified Chinese, Traditional Chinese, German, French, Italian,
Russian, Polish, Korean, Spanish, Brazilian Portuguese, Turkish, Hebrew,
Hungarian, Vietnamese

Strings are loaded by CStrTable (StrTable.*), keyed by the IDs in language.h. Each LanguageInfo carries a display name, BCP‑47 code, default font, and translator credit. Adding a language means dropping a new translated .ini into the language\ folder.

Note

Multilingual strings moved to external INI files in v1.86, which is why translators can add languages without recompiling.

12. Troubleshooting (Operational)

Issue: LibreHardwareMonitorLib.dll function acquisition failed, error code 127

Cause: The .NET bridge could not load the hardware library (missing/blocked DLL or missing .NET runtime). Error 127 = a required export/dependency was not found. (Reported in issue #2221.)

Resolution:

1. Confirm .NET Framework 4.5+ is installed.
2. Ensure LibreHardwareMonitorLib.dll is present next to the executable and not quarantined by antivirus.
3. If a newer LibreHardwareMonitor works standalone, replace the bundled LibreHardwareMonitorLib.dll with the newer one.
4. If unresolved, deploy the Lite version (no hardware library) or use the Hardware Monitor plugin.

Issue: Driver blocked by security software

Some security suites block LibreHardwareMonitorLib.sys. Whitelist it, or deploy the Lite version which never loads the driver.

Issue: High CPU/RAM or crashes after enabling hardware monitoring

Disable all items under General Settings → Hardware Monitoring, restart, and confirm stability. The hardware library is the most common crash source; the author cannot fix faults inside it.

Issue: GPU usage incorrect / shows integrated GPU

GPU monitoring depends on counter availability per driver. Intel GPU support was added in v1.85; behavior still varies by vendor/driver. (Related: issues #1627, #891.)

Issue: Net speed cannot be read after sleep/resume

Fixed in v1.86 (connections are re‑initialized after resume). If on an older build, switch the monitored adapter or restart.

Issue: "Unable to Save Settings"

The program folder is not writable. Either move it to a writable location, enable Save to AppData, or set portable_mode = false in global_cfg.ini. See User Guide for the full procedure.

13. Known Limitations & Improvement Areas

These are observations from the source and issue tracker, useful for maintainers and for setting deployment expectations.

• Windows 11 full‑taskbar overlap — when the taskbar is full, the embedded window can overlap icons; documented as currently unfixable. Mitigation is configuration‑only.
• Hardware/temperature stability — the LibreHardwareMonitor dependency is the dominant crash and resource‑usage source; the maintainer has effectively deprecated built‑in temperature in favor of the plugin. (Issues #2290, #2345, #2335, #2258.)
• CPU‑priority interaction — a community report (#2345) notes Explorer instability under high load related to CPU priority; a community workaround exists.
• config.ini whole‑file rewrite — SaveConfig() serializes the entire settings struct on exit, so concurrent/manual edits are overwritten. There is no partial/atomic write.
• Section‑name typo — the history section is persisted as [histroy_traffic] (misspelled in source). It must remain as‑is for backward compatibility; flagged here so administrators editing INI files use the exact key.
• Per‑user autostart only — no machine‑wide autostart; deployment scripts must configure each user.
• No app network control — repeated requests for per‑app network throttling/blocking (#2324) are out of scope; TrafficMonitor only observes traffic.
• Remote/web view — requested (#2133) but not implemented; the app is local‑only by design.

Suggested enhancements

• [ ] Atomic/partial config.ini writes to tolerate external edits and reduce data‑loss risk on crash during save.
• [ ] Optional plugin signature/allowlist to harden the plugin trust boundary in managed deployments.
• [ ] Make the optional netspeed decimals configurable (#1817).

14. Quick Reference

File & registry map

Hardware bitmask ([general] hardware_monitor_item)

Build matrix

Key source entry points