Magenta Hardware Components 详细技术文档

xiaoqionghui

314人浏览 · 2026-07-21 19:15:07

xiaoqionghui · 2026-07-21 19:15:07 发布

1. 概述

Magenta Hardware Components 是由 Magenta Systems Ltd 开发的一套免费 Delphi 硬件交互组件集，专为 Delphi 2007 至 Delphi 11.0 及更高版本设计。该组件集包含六个核心组件，旨在简化与 Windows 系统硬件、外设及底层 API 的交互开发，适用于需要串口通信、硬件事件监控、文件系统变化检测、GPS数据处理、防火墙管理及磁盘维护等功能的应用程序。

当前版本：v2.0（发布日期：2022年2月2日）
许可协议：免费软件（Freeware），但保留版权，可随时变更或撤销
开发商：Magenta Systems Ltd（英国）
下载文件大小：约 5.14 MB

下载地址:https://download.csdn.net/download/xiaoqionghui/93160124?spm=1001.2014.3001.5501

2. 组件详细说明

2.1 Magenta Serial Port Detection Component（串口检测组件）

核心功能：提供全面的系统串行 COM 端口枚举功能。它整合了多种检测方法，能够识别不同类型和安装方式的串口，并返回包含友好名称和安装信息的排序数组。

核心函数：EnumSerialPortsEx
该函数按以下顺序执行枚举：

查询注册表项 HLM\HARDWARE\DEVICEMAP\SERIALCOMM
枚举设备安装类 "Ports"（可发现包括USB串口在内的大多数串口）
可选地添加已禁用（但硬件未安装）的端口
枚举设备安装类 "CNCPorts"（用于 com0com 串口模拟器）
枚举设备安装类 "Modem"（可发现USB和内置调制解调器）

返回数据结构：动态数组 TSerialPort 记录，包含以下字段：

ComName：COM端口名称（如 "COM1"）
NumPort：端口编号
IntName：内部名称
FriendlyName：用户友好的Windows描述
Desc：描述
Manufacturer：制造商名称
HardwareId：硬件ID
Location：位置信息
StatInfo：状态信息
Enabled：是否启用（布尔值）

典型应用场景：

开发需要动态检测可用串口的工业控制软件
GPS接收器或串口设备管理工具
需要根据设备插拔状态自适应调整的程序

注意事项：

USB串口设备可能已安装但未插拔，此时 Enabled 字段为 False
虚拟串口（如com0com）可能返回字母名称（如CNCA0）
该单元需要三个Jedi JWA PI头文件：setupapi、Cfg、CfgMgr32（已包含在组件中）

2.2 Magenta Hardware Events Component（硬件事件监控组件）

核心功能：监听 Windows 硬件事件消息，并触发相应的事件处理程序，用于响应设备变化、磁盘卷变化、磁盘空间不足和电源事件。

组件类：THardwareEvents（可安装组件）
主要事件：

onLogEvent：设备硬件事件日志
onComPortEvent：串口事件（如插入/移除）
onVolumeEvent：磁盘卷变化事件
onLowSpaceEvent：磁盘空间不足事件
onPowerEvent：电源事件（如挂起、恢复、电池低电量等，返回PBT_xx值）
onRawEvent：原始设备变化消息

特性：组件创建后即开始监控，无需额外启动操作。

典型监控日志示例：

text

Device Change Message, event=0x8004
Old Serial Port Removed: COM5
Device Hardware Event: Old Serial Port Removed: COM5
New Serial Port Arrived: COM5
Device Hardware Event: New Serial Port Installed: COM5
New Disk Arrived, Volume: I
Device Hardware Event: Disk Change - New Disk Volume Installed: I

应用场景：

需要实时响应设备插拔的应用程序（如设备管理软件）
自动检测USB串口设备并重连的程序
监控外部存储设备接入并自动执行操作的工具
电源管理相关的应用程序

2.3 Directory Changes Monitoring Component（目录变更监控组件）

核心功能：基于 Damien Thouvenin 等人20多年前创建的 DirMon 组件更新而来，支持 Unicode 编译器。使用 Windows API ReadDirectoryChanges 监控指定目录或卷上的文件和目录变化。

组件类：TDirChange（可安装组件）
主要事件：

使用步骤：

设置 Path 属性（要监控的路径）
设置 WatchTree（是否监控子目录）
可选设置 WatchFilters（监控事件类型过滤）
将 Active 属性设为 True 开始监控

技术特性：

内部运行独立线程，事件从该线程回调
可监控指定卷或目录
支持子目录递归监控

监控日志示例：

text

DirChanged: Modified: ProgramData\Magenta-Systems\ComCap5\comcap5.current
DirChanged: Modified: Windows\Prefetch\SIGNALS.EXE-236B99F3.pf

应用场景：

文件同步工具
实时备份软件
开发环境文件变化自动构建工具
系统监控和日志分析程序

2.4 Magenta GPS and Location Component（GPS与定位组件）

核心功能：处理来自多种来源的GPS定位数据，并在检测到移动时触发事件。支持解析多种GPS协议，并提供了丰富的位置信息处理能力。

组件类：TMagGpsLoc（可安装组件）
支持的GPS数据源：

Windows Location API：适用于配备GPS传感器的Windows平板电脑和高端笔记本电脑
NMEA 0183：GPS接收器通用标准，处理 GGA, GSA, GSV, RMC, GLL, VTG 语句
GT02 GPS Tracker Protocol：Concox TR02等车辆跟踪器协议（GPS+GPRS+GSM组合）
TK102/103 Tracker Protocol：NMEA RMC语句的变体，包含日期时间、手机号、卫星数、IMEI等信息
WondeX/TK5000 Tracker Protocol：用于VT-10、VT300等设备，包含IMEI、时间、坐标、速度、方向

主要属性：

GpsType：选择传感器类型（GpsTypeLocApi, GpsTypeNMEA, GpsTypeGT02, GpsTypeTK10X, GpsTypeWondeX）
Latitude、Longitude、Altitude：当前位置信息
其他大量与具体传感器相关的属性

主要方法：

SetRecvData：以ASCII字符串形式传入传感器数据
GetDistance：计算两个经纬度坐标之间的距离（米）
GetNmeaInfo：列出传感器可见的GPS、格洛纳斯、伽利略卫星信息（NMEA模式）

事件：

OnLocationChange：位置变化（移动）时触发
OnStatusChange：传感器状态变化时触发

配套示例程序：Sensortest

支持通过串口（需Async Pro库）、UDP和TCP服务器接收数据
在Google地图上显示位置和移动轨迹（支持MSIE和Edge浏览器引擎）
包含坐标转换功能（WGS84转英国国家格网参考系统）

卫星信息示例输出：

text

Satellites in View = 28
Satellites Used = 21
PDOP = 1, HDOP = 0.7, VDOP = 0.7
Constellation: GPS
Satellite 10, Azimuth 293, Elevation 27, S/N 21, Fix
...
Constellation: Glonass
Satellite 73, Azimuth 251, Elevation 19, S/N 14, Fix
...
Constellation: Galileo
Satellite 2, Azimuth 54, Elevation 14, S/N 20, Fix

测试硬件（部分）：

GlobalSat BU-353-S4 USB GPS接收器（Prolific串口）
DIYmalls VK-162 USB GPS/格洛纳斯接收器（U-Blox模块）
Concox TR02车辆跟踪器
GlobalSat BT-359蓝牙GPS设备
安卓平板/手机（通过GPSd Forwarder应用发送NMEA数据包）

依赖库（示例程序需要）：

Async Pro串口库：https://github.com/TurboPack/AsyncPro
Internet Component Suite (ICS)：http://wiki.overbyte.eu/wiki/index.php/ICS_Download

特殊功能：

支持从Android/iOS移动应用接收位置跟踪数据
内置MagGpsConv单元，提供WGS84经纬度转英国国家格网（东向/北向）功能

2.5 Magenta Firewall Component（防火墙管理组件）

核心功能：通过COM自动化操作Windows Defender防火墙，搜索和列出防火墙规则与设置，并支持添加和删除规则。

主要函数：

MagFireWallAppsEnum：列出所有允许通过防火墙的应用程序文件
MagFireWallRulesAdd：添加防火墙规则（当前仅支持为应用程序添加入站访问规则）
MagFireWallRulesAdd：移除防火墙规则
MagFireWallServEnum：列出Windows服务的防火墙规则
MagFireWallRulesEnum：列出防火墙设置、活动配置文件及所有内置规则

应用列表示例输出：

text

Application Name: OverbyteIcsIpStmLogTst
Application Path: C:\delpcomp\ics\samples\delphi\sslinternet\overbyteicsipstmlogtst.exe
IP Version: Any
Scope: All
RemoteAddresses: *
Application Enabled: True

内置规则示例输出：

text

Rule Group: @FirewallAPI.dll,-32752
Rule Name: Network Discovery (SSDP-In)
Application Name: C:\WINDOWS\system32\svchost.exe
Service Name: Ssdpsrv
IP Protocol: UDP
Local Ports: 1900
RemoteAddresses: LocalSubnet
Direction: In
Rule Enabled: False
Profile: Domain
Rule Action: Allow

集成功能：

包含Inno Setup脚本代码（已注释），可在应用程序安装期间添加防火墙规则（安装程序以管理员权限运行）

注意事项：

仅管理员有权限添加或移除防火墙规则
当前版本仅支持添加应用的所有协议、地址和端口的入站访问规则
需要使用COM自动化，建议在调用函数前调用CoInitialize(nil);，之后调用CoUninitialize;

应用场景：

需要自动配置防火墙的服务器软件
安装程序中自动添加应用程序防火墙例外
网络管理工具

2.6 Magenta Check Disk and Format Disk Component（磁盘检查与格式化组件）

核心功能：封装了fmifs.dll中未公开的Windows API，用于格式化固定或可移动磁盘驱动器，并执行磁盘检查（支持Windows NT4及更高版本）。功能类似于Windows自带的格式化工具和CHKDSK工具。

组件类：TMagFmtChkDsk
支持的文件系统：NTFS、FAT32、exFAT（exFAT需操作系统支持）

技术背景：

fmifs.dll API由微软内部使用，未公开文档，由Sysinternals逆向工程
该组件基于Mark Russinovich的Chkdskx和Formatx命令行工具

关键特性：

支持任何已分配盘符的本地磁盘驱动器
可用于准备可移动备份驱动器
可格式化未使用的磁盘，可验证文件系统，但修复功能仅适用于未使用的驱动器
API设计为与用户交互，返回进度信息，组件解析这些消息并提供简化的返回信息

示例输出（磁盘检查）：

text

Starting Check Disk for H:
H:\ Volume Label: USBH, File System: NTFS
CHKDSK is verifying files (stage 1 of 3)...
File verification completed.
CHKDSK is verifying indexes (stage 2 of 3)...
Index verification completed.
CHKDSK is verifying security descriptors (stage 3 of 3)...
Security descriptor verification completed.
253167 KB total disk space.
250121 KB available on disk.
Check Disk: Finished OK

示例输出（格式化）：

text

Starting Format Disk for H:
H:\ Checking Existing Drive Format
H:\ Starting to Format Drive
Format Disk: Structure Created OK
Format Disk: Finished OK
H:\ New Volume Space: 256124416

应用场景：

磁盘管理工具
数据备份软件的预处理工具
系统维护工具
可移动存储设备初始化工具

3. 示例程序

组件包包含四个示例应用程序，展示了各组件的使用方法，所有示例均在Delphi 11.0中构建，并在Windows 11上测试通过：

示例程序	演示组件	说明
`signals.dpr`	TSerialPorts, THardwareEvents, TDirChange	测试串口检测、硬件事件和目录监控，需要Async Pro串口组件
`sensortest.dpr`	TMagGpsLoc	测试GPS定位组件，需要Async Pro和ICS库，包含地图显示（MSIE或Edge）
`firewalltest.dpr`	MagFirewall	测试防火墙管理功能，使用COM自动化
`diskfmt.dpr`	TMagFmtChkDsk	演示磁盘检查和格式化功能

4. 版本发布说明

v2.0（2022年2月2日）：首次公开发布。

5. 版权与联系方式

Magenta Hardware Components 为免费软件，但版权归 Magenta Systems Ltd 所有
开发商保留随时更改状态或撤回软件的权利，恕不另行通知

联系方式：

公司：Magenta Systems Ltd
地址：9 Vincent Road, Croydon CR0 6ED, United Kingdom
电话：020 8656 3636（英国）| +44 20 8656 3636（国际）
网站：https://www.magsys.co.uk/

6. 开发集成要点

兼容性：支持Delphi 2007至Delphi 11.0及更新版本
安装：下载后需按照Delphi组件安装流程添加到IDE
依赖性：
- 串口检测需要Jedi JWA头文件（已包含）
- GPS示例需要Async Pro和ICS库
- 防火墙功能依赖Windows COM自动化
权限要求：
- 防火墙操作需要管理员权限
- 磁盘格式化和检查可能需要管理员权限
平台支持：Windows NT4及更高版本（包括Windows 11）

7. 适用场景总结

组件	推荐应用领域
串口检测	工业自动化、医疗设备接口、POS系统、GPS数据采集
硬件事件监控	设备管理工具、自动配置系统、外设热插拔处理
目录监控	文件同步、备份软件、构建工具、审计系统
GPS定位	车辆跟踪、物流系统、户外导航、位置服务
防火墙管理	网络应用安装程序、安全管理工具
磁盘管理	系统维护工具、数据备份准备、存储设备管理