cSerialPort 方法详解

📋 方法列表

打开/关闭

方法名	返回类型	说明
`OpenPort`	Boolean	打开串口
`ClosePort`	-	关闭串口
`ApplyConfig`	-	重新应用配置到已打开端口
`RefreshConfig`	-	从端口读取当前配置

读取

方法名	返回类型	说明
`ReadData`	Long	读取字节数组
`ReadText`	String	读取文本
`ReadExisting`	String	非阻塞读取所有现有数据
`ReadByte`	Integer	读取单字节(0~255)，超时返回 -1
`ReadLine`	String	读取一行

写入

方法名	返回类型	说明
`WriteData`	Long	写入字节数组
`WriteText`	Long	写入文本
`WriteByte`	-	写入单字节
`WriteLine`	Long	写入一行（自动追加换行符）
`TransmitImmediate`	Boolean	优先传输字符，绕过缓冲区

信号线

方法名	说明
`SetDTR`	设置 DTR 信号
`SetRTS`	设置 RTS 信号
`SetBreak`	设置/清除 Break 信号
`SendXOff`	发送 XOFF
`SendXOn`	发送 XON

缓冲区

方法名	说明
`PurgeRx`	清空接收缓冲区
`PurgeTx`	清空发送缓冲区
`PurgeAll`	清空所有缓冲区

监控

方法名	返回类型	说明
`StartMonitoring`	Boolean	开始异步监控
`StopMonitoring`	-	停止监控
`WaitForEvent`	Long	阻塞等待事件（慎用）
`GetEventMask`	Long	获取当前事件掩码

诊断

方法名	返回类型	说明
`GetStatusString`	String	获取完整状态字符串
`ReadCommErrors`	Long	获取通信错误码
`ReadModemStatus`	Long	获取 Modem 状态字
`ResetCounters`	-	重置收发计数

🔓 OpenPort

说明

打开串口。内部自动处理 \\.\COMx 前缀，支持 COM10 以上端口。

语法

Public Function OpenPort(Optional ByVal Port As String, _
                         Optional ByVal Config As cSerialConfig) As Boolean

参数

参数	类型	说明
`Port`	String（可选）	端口名，如 "COM3"
`Config`	cSerialConfig（可选）	配置对象

返回值

成功返回 True，失败返回 False 并设置 LastError。

使用示例

' 方式一：先设属性再打开
sp.PortName = "COM3"
sp.Config.BaudRate = br115200
If sp.OpenPort() Then Debug.Print "打开成功"

' 方式二：参数方式
Dim cfg As New cSerialConfig
cfg.BaudRate = br9600
sp.OpenPort "COM3", cfg

打开流程

1. CreateFile 打开 \\.\COMx
2. SetupComm 设置缓冲区大小
3. SetCommState 应用 DCB 配置
4. SetCommTimeouts 应用超时配置
5. PurgeComm 清空缓冲区

🔒 ClosePort

说明

关闭串口并释放句柄。若正在监控会先停止。

sp.ClosePort

Class_Terminate 会自动调用此方法。

📤 WriteText

说明

写入文本，使用 StrConv 转 ANSI 字节后发送。

语法

Public Function WriteText(ByVal Text As String) As Long

返回值

实际写入的字节数。

Dim n As Long
n = sp.WriteText("Hello")
Debug.Print "发送 " & n & " 字节"

📤 WriteData

说明

写入字节数组，适用于二进制协议。

语法

Public Function WriteData(Buffer() As Byte) As Long

Dim buf(2) As Byte
buf(0) = &H41: buf(1) = &H42: buf(2) = &H43
sp.WriteData buf     ' 发送 ABC

📤 WriteLine

说明

写入一行文本，自动追加换行符（默认 vbCrLf）。

语法

Public Function WriteLine(ByVal Text As String, _
                          Optional ByVal Terminator As String = vbCrLf) As Long

sp.WriteLine "Hello"           ' 发送 "Hello" & vbCrLf
sp.WriteLine "Data", vbLf      ' 自定义结束符

📤 TransmitImmediate

说明

优先传输字符，绕过发送缓冲区直接发送。

sp.TransmitImmediate &H55   ' 立即发送 0x55

📥 ReadExisting

说明

非阻塞读取输入缓冲区中所有现有数据。

Dim s As String
s = sp.ReadExisting()
If Len(s) > 0 Then Debug.Print "收到: " & s

📥 ReadData

说明

读取字节数组。

语法

Public Function ReadData(Buffer() As Byte, _
                         Optional ByVal BytesToRead As Long = -1) As Long

参数

参数	类型	说明
`Buffer`	Byte()	输出缓冲区，自动 ReDim
`BytesToRead`	Long（可选）	要读取的字节数，-1 表示读取全部

返回值

实际读取的字节数。

Dim buf() As Byte
Dim n As Long
n = sp.ReadData(buf)          ' 读取全部
n = sp.ReadData(buf, 10)      ' 读取最多10字节

📥 ReadLine

说明

读取一行，默认以 vbCrLf 结尾。可能阻塞直到收到完整行或超时。

语法

Public Function ReadLine(Optional ByVal Terminator As String = vbCrLf) As String

sp.Config.SetReadTimeout 5000   ' 设置超时
Dim line As String
line = sp.ReadLine()             ' 读取一行

📡 StartMonitoring

说明

开始异步监控，使用 Win32 Timer 定时轮询缓冲区。检测到新数据触发 DataReceived 事件。

语法

Public Function StartMonitoring(Optional ByVal IntervalMs As Long = 50) As Boolean

sp.StartMonitoring 50    ' 50ms 轮询
sp.StartMonitoring       ' 默认50ms

📡 StopMonitoring

停止异步监控。

sp.StopMonitoring

⚠️ WaitForEvent

说明

阻塞式等待通信事件。

语法

Public Function WaitForEvent(ByVal EventMask As Long) As Long

参数

参数	类型	说明
`EventMask`	Long	事件组合，如 `EV_RXCHAR Or EV_CTS`

返回值

实际发生的事件掩码，0 表示失败。

⚠️ 警告：此方法会阻塞调用线程！在 UI 线程中使用将冻结界面。建议仅在后台线程或控制台应用中使用，常规场景请用 StartMonitoring。

🔧 SetDTR / SetRTS

说明

手动设置 DTR/RTS 信号线。注意：如果配置了硬件流控制（fcRtsCts/fcDtrDsr），手动设置可能被流控制覆盖。

sp.SetDTR True
sp.SetRTS True
sp.SetDTR False
sp.SetRTS False

🔧 SetBreak

说明

设置或清除 Break 信号。Break 信号会使数据线保持为0状态。

sp.SetBreak True        ' 开始发送 Break
' 延时...
sp.SetBreak False       ' 停止 Break

🧹 PurgeRx / PurgeTx / PurgeAll

说明

清空缓冲区。

方法	说明
`PurgeRx`	清空接收缓冲区
`PurgeTx`	清空发送缓冲区
`PurgeAll`	清空所有缓冲区，终止所有挂起的 I/O

sp.PurgeAll     ' 清空所有

📊 GetStatusString

说明

获取当前串口完整状态字符串，用于调试。

Debug.Print sp.GetStatusString()

输出示例：

Port: COM3
Open: True
BaudRate: 115200
DataBits: 8
InBuffer: 0
CTS: True
Received: 128
Sent: 64
Monitoring: True

🔄 ApplyConfig / RefreshConfig

方法	说明
`ApplyConfig`	将当前 `Config` 重新应用到已打开的端口
`RefreshConfig`	从端口读取当前 DCB/超时并更新 `Config`

sp.OpenPort
sp.Config.BaudRate = br9600
sp.ApplyConfig          ' 应用新配置

sp.RefreshConfig        ' 从端口读取实际配置
Debug.Print sp.Config.BaudRate

📊 EnumSerialPorts

说明

枚举系统中可用的串口号（定义在 modSerialPortAPI 模块中）。

语法

Public Function EnumSerialPorts() As Collection

Dim ports As Collection
Set ports = EnumSerialPorts()
Dim p As Variant
For Each p In ports
    Debug.Print p
Next

最后更新: 2026-07-05

cSerialPort 方法详解 ​

📋 方法列表 ​

打开/关闭 ​

读取 ​

写入 ​

信号线 ​

缓冲区 ​

监控 ​

诊断 ​

🔓 OpenPort ​

说明 ​

语法 ​

参数 ​

返回值 ​

使用示例 ​

打开流程 ​

🔒 ClosePort ​

说明 ​

📤 WriteText ​

说明 ​

语法 ​

返回值 ​

📤 WriteData ​

说明 ​

语法 ​

📤 WriteLine ​

说明 ​

语法 ​

📤 TransmitImmediate ​

说明 ​

📥 ReadExisting ​

说明 ​

📥 ReadData ​

说明 ​

语法 ​

参数 ​

返回值 ​

📥 ReadLine ​

说明 ​

语法 ​

📡 StartMonitoring ​

说明 ​

语法 ​

📡 StopMonitoring ​

⚠️ WaitForEvent ​

说明 ​

语法 ​

参数 ​

返回值 ​

🔧 SetDTR / SetRTS ​

说明 ​

🔧 SetBreak ​

说明 ​

🧹 PurgeRx / PurgeTx / PurgeAll ​

说明 ​

📊 GetStatusString ​

说明 ​

🔄 ApplyConfig / RefreshConfig ​

📊 EnumSerialPorts ​

说明 ​

语法 ​

cSerialPort 方法详解

📋 方法列表

打开/关闭

读取

写入

信号线

缓冲区

监控

诊断

🔓 OpenPort

说明

语法

参数

返回值

使用示例

打开流程

🔒 ClosePort

说明

📤 WriteText

说明

语法

返回值

📤 WriteData

说明

语法

📤 WriteLine

说明

语法

📤 TransmitImmediate

说明

📥 ReadExisting

说明

📥 ReadData

说明

语法

参数

返回值

📥 ReadLine

说明

语法

📡 StartMonitoring

说明

语法

📡 StopMonitoring

⚠️ WaitForEvent

说明

语法

参数

返回值

🔧 SetDTR / SetRTS

说明

🔧 SetBreak

说明

🧹 PurgeRx / PurgeTx / PurgeAll

说明

📊 GetStatusString

说明

🔄 ApplyConfig / RefreshConfig

📊 EnumSerialPorts

说明

语法