C++串口类实现

沈跃泉2026-04-14 13:44

C++ 串口类实现

一个轻量、线程安全的 Windows 串口通信封装类。

概述

在 Windows 平台下操作串口，需要调用 Win32 API CreateFile、ReadFile、WriteFile 等，代码稍显繁琐。本类对串口的打开、配置、读写操作进行封装，提供简洁的 C++ 接口，并内置了接收线程和回调机制。

源码共 3 个文件：

文件 说明
SerialPort.h 类声明
SerialPort.cpp 完整实现
main.cpp 使用示例

头文件 SerialPort.h

cpp 复制代码 
#pragma once
#include <windows.h>
#include <string>
#include <vector>
#include <thread>
#include <atomic>
#include <functional>
#include <mutex>

class SerialPort {
public:
    SerialPort();
    ~SerialPort();

    bool open(const std::string& portName, unsigned long baudRate);
    void close();
    bool isOpen() const;
    std::string getLastError() const;

    // 发送数据（线程安全）
    bool write(const std::vector<unsigned char>& data);
    bool write(const std::string& s);

    // 设置接收回调
    void setReceiveCallback(std::function<void(const std::vector<unsigned char>&)> cb);

private:
    void receiveLoop();

    HANDLE m_handle;
    std::atomic<bool> m_running;
    std::thread m_thread;
    std::string m_lastError;
    std::function<void(const std::vector<unsigned char>&)> m_callback;
    std::mutex m_writeMutex;
};

设计要点

  • std::atomic<bool> m_running ：跨线程共享的运行标志，比 volatile bool 更安全。
  • std::mutex m_writeMutex ：写操作加锁，保证多线程并发调用 write() 时的线程安全。
  • std::function 回调：用户可通过 lambda、函数指针等灵活注册数据接收处理逻辑。
  • RAII 析构 ：close() 在析构函数中自动调用，确保资源释放。

实现 SerialPort.cpp

构造函数与析构

cpp 复制代码 
SerialPort::SerialPort()
    : m_handle(INVALID_HANDLE_VALUE), m_running(false)
{
}

SerialPort::~SerialPort()
{
    close();
}

析构调用 close()，保证对象销毁时串口一定被关闭。

错误信息辅助函数

cpp 复制代码 
static std::string GetLastErrorAsString(DWORD err)
{
    if (err == 0) return std::string();
    LPSTR messageBuffer = nullptr;
    DWORD size = FormatMessageA(FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS,
        nullptr, err, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), (LPSTR)&messageBuffer, 0, nullptr);
    std::string message;
    if (messageBuffer && size > 0) message.assign(messageBuffer, size);
    if (messageBuffer) LocalFree(messageBuffer);
    return message;
}

将 Windows API 的错误码转换为可读的字符串，供调试使用。

打开串口 open()

cpp 复制代码 
bool SerialPort::open(const std::string& portName, unsigned long baudRate)
{
    if (isOpen()) return true;

    std::string fullName = portName;
    if (portName.rfind("\\\\.", 0) != 0) {
        fullName = "\\\\.\\" + portName;
    }

    m_handle = CreateFileA(fullName.c_str(),
        GENERIC_READ | GENERIC_WRITE,
        0, nullptr, OPEN_EXISTING, 0, nullptr);
  1. 路径格式 ：Windows 上超过 COM9 的串口名（如 COM10、COM\.\ PHYSICALCOM0）需要加 \\.\ 前缀。代码自动补全。
  2. 同步模式：使用同步 I/O，接收由独立线程负责，避免阻塞主线程。
cpp 复制代码 
    DCB dcb;
    SecureZeroMemory(&dcb, sizeof(dcb));
    dcb.DCBlength = sizeof(dcb);
    if (!GetCommState(m_handle, &dcb)) { /* ... */ }

    dcb.BaudRate = baudRate;
    dcb.ByteSize = 8;
    dcb.Parity = NOPARITY;
    dcb.StopBits = ONESTOPBIT;
    if (!SetCommState(m_handle, &dcb)) { /* ... */ }

通过 DCB 结构配置波特率、数据位、校验位、停止位，默认 8N1。

cpp 复制代码 
    COMMTIMEOUTS timeouts;
    timeouts.ReadIntervalTimeout = 50;
    timeouts.ReadTotalTimeoutMultiplier = 0;
    timeouts.ReadTotalTimeoutConstant = 50;
    timeouts.WriteTotalTimeoutMultiplier = 0;
    timeouts.WriteTotalTimeoutConstant = 50;
    SetCommTimeouts(m_handle, &timeouts);

    PurgeComm(m_handle, PURGE_RXCLEAR | PURGE_TXCLEAR | PURGE_RXABORT | PURGE_TXABORT);

    m_running = true;
    m_thread = std::thread(&SerialPort::receiveLoop, this);
    return true;
}
  • 超时设置 ：Read 每次最多等待 50ms，防止 ReadFile 永久阻塞。
  • 清空缓冲区 ：PurgeComm 丢弃旧数据。
  • 启动接收线程 ：receiveLoop() 在独立线程中运行。

关闭串口 close()

cpp 复制代码 
void SerialPort::close()
{
    if (!isOpen()) return;

    m_running = false;
    CancelIoEx(m_handle, nullptr);   // 取消阻塞中的 IO

    if (m_thread.joinable()) m_thread.join();

    if (m_handle != INVALID_HANDLE_VALUE) {
        CloseHandle(m_handle);
        m_handle = INVALID_HANDLE_VALUE;
    }
}

关键点：

  1. m_running = false 通知接收线程退出。
  2. CancelIoEx 中断 ReadFile，配合超时设置使线程尽快退出。
  3. join() 等待线程结束，避免析构时线程仍运行。
  4. 最后才 CloseHandle，保证线程已安全退出。

发送数据 write()

cpp 复制代码 
bool SerialPort::write(const std::vector<unsigned char>& data)
{
    if (!isOpen()) { m_lastError = "Port not open"; return false; }

    std::lock_guard<std::mutex> lock(m_writeMutex);

    DWORD bytesWritten = 0;
    BOOL ok = WriteFile(m_handle, data.data(), static_cast<DWORD>(data.size()), &bytesWritten, nullptr);
    if (!ok) { m_lastError = "WriteFile failed: " + GetLastErrorAsString(GetLastError()); return false; }

    return bytesWritten == data.size();
}

bool SerialPort::write(const std::string& s)
{
    return write(std::vector<unsigned char>(s.begin(), s.end()));
}
  • 写锁 ：std::lock_guard 保证多线程同时调用 write() 时不会产生竞态。
  • 两个重载：一个接受字节数组，一个接受字符串，使用更方便。

接收回调 setReceiveCallback()

cpp 复制代码 
void SerialPort::setReceiveCallback(std::function<void(const std::vector<unsigned char>&)> cb)
{
    m_callback = std::move(cb);
}

使用 std::move 避免不必要的拷贝。

接收线程 receiveLoop()

cpp 复制代码 
void SerialPort::receiveLoop()
{
    const DWORD bufSize = 1024;
    std::vector<unsigned char> buffer(bufSize);

    while (m_running && isOpen()) {
        DWORD bytesRead = 0;
        BOOL ok = ReadFile(m_handle, buffer.data(), bufSize, &bytesRead, nullptr);
        if (!ok) {
            DWORD err = GetLastError();
            if (err != ERROR_IO_PENDING && err != ERROR_TIMEOUT && err != ERROR_SUCCESS) {
                m_lastError = "ReadFile failed: " + GetLastErrorAsString(err);
                break;
            }
        }

        if (bytesRead > 0) {
            std::vector<unsigned char> data(buffer.begin(), buffer.begin() + bytesRead);
            if (m_callback) {
                try { m_callback(data); }
                catch (...) { /* 忽略回调异常 */ }
            }
            else {
                // 默认打印：可打印字符 + HEX
                std::cout << "[串口接收] 字符: " << printable << "  HEX: " << ossHex.str() << std::endl;
            }
        }

        std::this_thread::sleep_for(std::chrono::milliseconds(10));
    }
}

逻辑说明：

  1. 循环读取，直到 m_running 为 false 或发生错误。
  2. ReadFile 在超时设置下最多阻塞 50ms，之后返回，即使未读到任何数据。
  3. 读到数据后：优先调用用户回调；无回调时默认打印 HEX + 可打印字符。
  4. 回调异常捕获：防止用户回调中的崩溃影响串口接收线程。
  5. 每次循环 sleep_for(10ms) 降低 CPU 占用。

完整源码

SerialPort.h

cpp 复制代码 
#pragma once
#include <windows.h>
#include <string>
#include <vector>
#include <thread>
#include <atomic>
#include <functional>
#include <mutex>

class SerialPort {
public:
    SerialPort();
    ~SerialPort();

    bool open(const std::string& portName, unsigned long baudRate);
    void close();
    bool isOpen() const;
    std::string getLastError() const;

    // 发送数据（线程安全）
    bool write(const std::vector<unsigned char>& data);
    bool write(const std::string& s);

    // 设置接收回调
    void setReceiveCallback(std::function<void(const std::vector<unsigned char>&)> cb);

private:
    void receiveLoop();

    HANDLE m_handle;
    std::atomic<bool> m_running;
    std::thread m_thread;
    std::string m_lastError;
    std::function<void(const std::vector<unsigned char>&)> m_callback;
    std::mutex m_writeMutex;
};

SerialPort.cpp

cpp 复制代码 
#include "SerialPort.h"
#include <iostream>
#include <sstream>
#include <chrono>
#include <iomanip>
#include <mutex>

SerialPort::SerialPort()
    : m_handle(INVALID_HANDLE_VALUE), m_running(false)
{
}

SerialPort::~SerialPort()
{
    close();
}

static std::string GetLastErrorAsString(DWORD err)
{
    if (err == 0) return std::string();
    LPSTR messageBuffer = nullptr;
    DWORD size = FormatMessageA(FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS,
        nullptr, err, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), (LPSTR)&messageBuffer, 0, nullptr);
    std::string message;
    if (messageBuffer && size > 0) message.assign(messageBuffer, size);
    if (messageBuffer) LocalFree(messageBuffer);
    return message;
}

bool SerialPort::open(const std::string& portName, unsigned long baudRate)
{
    if (isOpen()) return true;

    std::string fullName = portName;
    if (portName.rfind("\\\\.", 0) != 0) {
        fullName = "\\\\.\\" + portName;
    }

    m_handle = CreateFileA(fullName.c_str(),
        GENERIC_READ | GENERIC_WRITE,
        0,
        nullptr,
        OPEN_EXISTING,
        0,
        nullptr);

    if (m_handle == INVALID_HANDLE_VALUE) {
        m_lastError = "CreateFile failed: " + GetLastErrorAsString(GetLastError());
        return false;
    }

    DCB dcb;
    SecureZeroMemory(&dcb, sizeof(dcb));
    dcb.DCBlength = sizeof(dcb);
    if (!GetCommState(m_handle, &dcb)) {
        m_lastError = "GetCommState failed: " + GetLastErrorAsString(GetLastError());
        CloseHandle(m_handle);
        m_handle = INVALID_HANDLE_VALUE;
        return false;
    }

    dcb.BaudRate = baudRate;
    dcb.ByteSize = 8;
    dcb.Parity = NOPARITY;
    dcb.StopBits = ONESTOPBIT;
    if (!SetCommState(m_handle, &dcb)) {
        m_lastError = "SetCommState failed: " + GetLastErrorAsString(GetLastError());
        CloseHandle(m_handle);
        m_handle = INVALID_HANDLE_VALUE;
        return false;
    }

    COMMTIMEOUTS timeouts;
    timeouts.ReadIntervalTimeout = 50;
    timeouts.ReadTotalTimeoutMultiplier = 0;
    timeouts.ReadTotalTimeoutConstant = 50;
    timeouts.WriteTotalTimeoutMultiplier = 0;
    timeouts.WriteTotalTimeoutConstant = 50;
    SetCommTimeouts(m_handle, &timeouts);

    PurgeComm(m_handle, PURGE_RXCLEAR | PURGE_TXCLEAR | PURGE_RXABORT | PURGE_TXABORT);

    m_running = true;
    m_thread = std::thread(&SerialPort::receiveLoop, this);
    return true;
}

void SerialPort::close()
{
    if (!isOpen()) return;

    m_running = false;

    // 取消可能的阻塞 IO，尝试使 ReadFile 返回
    CancelIoEx(m_handle, nullptr);

    if (m_thread.joinable()) m_thread.join();

    if (m_handle != INVALID_HANDLE_VALUE) {
        CloseHandle(m_handle);
        m_handle = INVALID_HANDLE_VALUE;
    }
}

bool SerialPort::isOpen() const
{
    return m_handle != INVALID_HANDLE_VALUE;
}

std::string SerialPort::getLastError() const
{
    return m_lastError;
}

bool SerialPort::write(const std::vector<unsigned char>& data)
{
    if (!isOpen()) {
        m_lastError = "Port not open";
        return false;
    }

    std::lock_guard<std::mutex> lock(m_writeMutex);

    DWORD bytesWritten = 0;
    BOOL ok = WriteFile(m_handle, data.data(), static_cast<DWORD>(data.size()), &bytesWritten, nullptr);
    if (!ok) {
        m_lastError = "WriteFile failed: " + GetLastErrorAsString(GetLastError());
        return false;
    }

    return bytesWritten == data.size();
}

bool SerialPort::write(const std::string& s)
{
    return write(std::vector<unsigned char>(s.begin(), s.end()));
}

void SerialPort::setReceiveCallback(std::function<void(const std::vector<unsigned char>&)> cb)
{
    m_callback = std::move(cb);
}

void SerialPort::receiveLoop()
{
    const DWORD bufSize = 1024;
    std::vector<unsigned char> buffer(bufSize);

    while (m_running && isOpen()) {
        DWORD bytesRead = 0;
        BOOL ok = ReadFile(m_handle, buffer.data(), bufSize, &bytesRead, nullptr);
        if (!ok) {
            DWORD err = GetLastError();
            if (err != ERROR_IO_PENDING && err != ERROR_TIMEOUT && err != ERROR_SUCCESS) {
                m_lastError = "ReadFile failed: " + GetLastErrorAsString(err);
                break;
            }
        }

        if (bytesRead > 0) {
            std::vector<unsigned char> data(buffer.begin(), buffer.begin() + bytesRead);
            if (m_callback) {
                try {
                    m_callback(data);
                }
                catch (...) {
                    // 忽略回调异常
                }
            }
            else {
                std::ostringstream ossHex;
                std::string printable;
                for (unsigned char b : data) {
                    if (b >= 0x20 && b <= 0x7E) printable.push_back(static_cast<char>(b));
                    else printable.push_back('.');
                    ossHex << std::hex << std::uppercase << std::setw(2) << std::setfill('0')
                        << static_cast<int>(b) << ' ';
                }
                // 注意：此处为线程中打印，若需线程安全或按序输出可改为其他机制
                std::cout << "[串口接收] 字符: " << printable << "  HEX: " << ossHex.str() << std::endl;
            }
        }

        std::this_thread::sleep_for(std::chrono::milliseconds(10));
    }
}

使用示例 main.cpp

cpp 复制代码 
#include <conio.h>
#include <iostream>
#include <iomanip>
#include <sstream>
#include <thread>
#include "SerialPort.h"
#include <io.h>
#include <fcntl.h>
#include <windows.h>

void recvFunc(const std::vector<unsigned char>& data)
{
    std::ostringstream ossHex;
    std::string printable;
    for (unsigned char b : data) {
        if (b >= 0x20 && b <= 0x7E) printable.push_back(static_cast<char>(b));
        else printable.push_back('.');
        ossHex << std::hex << std::uppercase << std::setw(2) << std::setfill('0')
            << static_cast<int>(b) << ' ';
    }
    // use ASCII prefix to avoid encoding issues in callback thread
    std::cout << "[Receive] ASCII: " << printable << "  HEX: " << ossHex.str() << std::endl;
}

int main()
{
    // 演示串口类的简单使用（需要真实串口才能收到数据）
    SerialPort sp;
    // 示例：打开 COM3，115200 波特（根据实际串口修改）
    if (sp.open("COM3", CBR_115200)) {
        std::cout << "start recv" << std::endl;

        // Start the receive thread
		sp.setReceiveCallback(recvFunc);

        // 示例：发送字节 0x55 0xAA
        {
            std::vector<unsigned char> pkt = { 0x55, 0xAA };
            if (sp.write(pkt)) {
                std::cout << "已发送: 0x55 0xAA" << std::endl;
            } else {
                std::cout << "发送失败: " << sp.getLastError() << std::endl;
            }
        }

        system("pause");

        sp.close();
        std::cout << "串口已关闭。\n";
    }
    else {
        std::cout << "打开串口失败：\n";
        std::cout << sp.getLastError() << "\n";
    }

    return 0;
}
相关推荐
智者知已应修善业11 小时前
【51单片机非精准计时2个外部中断启停】2023-5-29
c++·经验分享·笔记·算法·51单片机
沐雪轻挽萤11 小时前
3. C++17新特性-带初始化的 if 和 switch 语句
开发语言·c++
Magic--11 小时前
C++ 智能指针
开发语言·c++·算法
呱呱巨基11 小时前
网络基础概念
linux·网络·c++·笔记·学习
飞鼠_12 小时前
详解c++中的sturct
开发语言·c++
dashizhi201512 小时前
电脑禁用U口、禁用USB端口、屏蔽移动存储设备使用的方法
windows·安全·电脑
CoderCodingNo12 小时前
【GESP】C++一级真题 luogu-B4495, [GESP202603 一级] 交朋友
开发语言·c++
梦游钓鱼12 小时前
stl常用容器说明
开发语言·c++
航Hang*12 小时前
Windows Server 配置与管理——第10章：配置FTP服务器
运维·服务器·网络·windows·学习·vmware
热门推荐
012026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元02GitHub 镜像站点03一周AI热点速览（2026.03.31-04.06）：GPT-6曝光、谷歌开源Gemma 4、资本狂飙与模型军备竞赛04基于 Docker 部署 Hermes Agent 并接入飞书机器人的完整指南05GPT-6核心能力解析及与现有主流大模型对比06免费！不限量！用opencode接入英伟达（NVIDIA）大模型，轻松打造你的 AI 编程助手07零成本！Ollama本地部署国产大模型全指南（支持Kimi-K2.5/GLM-5/Qwen，新手秒上手）08从限购到畅通：GLM-5.1 Coding Plan接入攻略09CodeBuddy与WorkBuddy深度对比：腾讯两款AI工具差异及实操指南10LLM Wiki：让大模型替你打理知识库的完整指南