C++/WinRT BLE开发：广播扫描与GATT Notify实战

简介：面向希望在 Windows 平台用 C/C++ 直接操控低功耗蓝牙的开发者，这套工程示例以 WinRT 接口为核心，演示 BLE 设备枚举、广播扫描、服务与特征值读写、通知订阅等常见流程，适合有一定 C++ 基础、需在桌面端集成蓝牙通信或排查连接问题的初中级工程师参考。

压缩包共 11 个文件，约 10KB，含 4 个 .h 头文件、4 个 .cpp 源文件及 vcxproj 工程、filters 筛选配置和 .user 用户配置，可直接用 Visual Studio 打开并按模块拆分学习；头文件定义接口与数据结构，源文件承担设备句柄管理与通信逻辑，便于对照修改。

目前已有 5966 人学习下载。借助这份可编译的工程骨架，读者能理清 WinRT 异步调用与 GATT 交互的组织方式，掌握扫描回调、特征值操作和异常处理思路，并以此为起点扩展自己的 BLE 上位机或设备调试工具，减少从零搭建工程的时间。

1. 从一次“扫不到设备”的现场说起

去年帮朋友排查一个产线工装，场景很典型：一个 BLE 温湿度传感器，用手机 App 打开就出数据，换成他们自己写的 Windows 桌面程序，C/C++那边调半天，扫描列表一直是空的。换成别的 USB 转串口方案，成本又上去了。问题不在硬件，而在 Windows 这套BLE蓝牙 API 的分层：广播扫描、连接、GATT 读写是三段独立的状态机，任何一段的缓存或者生命周期没管对，表现就是“什么都没有”。

这份资源就是围绕这条链路做的可编译示例：用C++/WinRT拉起广播监听，解析 AD 结构，按地址连上设备，枚举服务和特征，写入指令并订阅 Notify 回包。它适合已经会用 C++ 但被 Windows 蓝牙折腾过的人，也适合想把桌面端接到一个 BLE 模组上的嵌入式同事。往下我会按项目实际的目录和调用顺序拆，不讲概念堆砌，直接说这段代码为什么这么写、哪里最容易翻车。

2. 技术选型与工程骨架：三条 API 路径怎么选

2.1 C++/WinRT、bthledef、SetupAPI 的能力边界

Windows 上做 BLE，能走的路其实不止一条，新人最容易在选型阶段就栽跟头。项目最终采用的是C++/WinRT这一套，也就是头文件<winrt/Windows.Devices.Bluetooth.Advertisement.h>、<winrt/Windows.Devices.Bluetooth.GenericAttributeProfile.h>这种投影方式。原因是它把广播包、服务、特征都做成了对象模型，异步用co_await串起来，可读性比裸结构体好太多。

另外两条路也得知道存在，不然遇到 WinRT 覆盖不到的场景会卡住。bthledef.h那套传统 Win32 蓝牙 API，函数名是BluetoothGATTGetServices、BluetoothGATTGetCharacteristics这种，全靠调用方预分配缓冲、传BTH_LE_GATT_SERVICE结构体数组，代码量大但胜在可控，某些老系统或者需要精细控制重叠 IO 的场合还得用它。SetupAPI配合GUID_BLUETOOTHLE_DEVICE_INTERFACE主要用于枚举设备接口和拿CreateFile的句柄，配对和诊断有时候绕不开。

选型结论很直接：日常的扫描 + 连接 + 读写，一律先用C++/WinRT；只有当你要拿某些 WinRT 没暴露的底层字段，或者需要在没有 C++/WinRT 运行时的极简环境里跑，才退回bthledef。项目里保留了一个win32_fallback.cpp的小文件，就是给这种降级留的口子。

2.2 目录结构与 CMake 构建配置

工程结构照着职责切，不按“头文件/源文件”切，这样后面接业务协议时改动面小：

ble_demo/ ├── CMakeLists.txt ├── src/ │ ├── main.cpp # 入口，init_apartment + 阻塞 │ ├── ble_scanner.h/.cpp # 广播监听与包解析 │ ├── ble_device.h/.cpp # 连接、断线重连、设备生命周期 │ ├── gatt_client.h/.cpp # 服务/特征枚举、读写、Notify │ ├── protocol_codec.h/.cpp # 业务帧编解码，与 BLE 层解耦 │ └── log.h # 轻量日志，带线程 id └── test/ └── codec_test.cpp # 纯逻辑单测，不依赖硬件

CMakeLists.txt里有两个关键点：链接windowsapp.lib，以及开启协程支持。C++/WinRT的异步返回的是IAsyncOperation，没有/await或者 C++20 协程就co_await不了。

cmake_minimum_required(VERSION 3.20) project(ble_demo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 20) set(CMAKE_CXX_STANDARD_REQUIRED ON) add_executable(ble_demo src/main.cpp src/ble_scanner.cpp src/ble_device.cpp src/gatt_client.cpp src/protocol_codec.cpp ) # windowsapp.lib 是 WinRT 投影的运行库，缺了会在链接期报一堆 unresolved target_link_libraries(ble_demo PRIVATE windowsapp) # /await 用于协程；和 /std:c++20 同时开时若冲突，退到 /std:c++latest target_compile_options(ble_demo PRIVATE /await /EHsc /W4)

这里有个血泪经验：如果编译器版本偏旧，/std:c++20和/await会打架，报的是语法错误而不是明确提示，看着像代码写错了，实际是开关组合问题。我一般先用/std:c++latest验证能否编过，再往下调标准版本。

提示：用vcpkg的话不需要额外装包，C++/WinRT的头文件随 Windows SDK 一起提供，装好 SDK 就能#include <winrt/...>。

2.3 最小可跑骨架：初始化与进程存活

main.cpp做的事情不多，但每一行都不能少。winrt::init_apartment必须在任何 WinRT 调用之前执行，一个线程只能调一次，重复调用会抛异常。项目选的是multi_threaded（MTA），因为蓝牙回调本来就来自线程池，强行绑 STA 反而要自己做消息泵。

#include <winrt/base.h> #include <winrt/Windows.Foundation.h> #include <iostream> // 前向声明，真正的会话逻辑在 ble_device.cpp 里 winrt::fire_and_forget run_session(std::string target_name); int main() { // 初始化 WinRT 运行时，MTA 模式适配线程池回调 winrt::init_apartment(winrt::apartment_type::multi_threaded); run_session("TH-Sensor"); // 协程是 fire_and_forget 的，主线程必须活着，否则进程退出协程被掐断 std::string line; std::getline(std::cin, line); return 0; }

fire_and_forget表示这个协程不需要调用方等待结果，异常也会被吞掉，所以内部一定要自己 try/catch 并把错误写日志，否则出问题时就是个黑匣子，什么都看不到。最后用std::getline卡住主线程，是最省事的保活方式；如果是 GUI 程序，换成消息循环即可，道理一样。

3. 广播扫描：BluetoothLEAdvertisementWatcher 的解析链路

3.1 AD 结构解析：从原始段到可用字段

广播包在 Windows 这层已经被拆成了DataSections()，每一段带DataType()和Data()。但DataType是原始 AD Type 数值，业务字段还是得自己按类型归位。项目里的解析函数统一输出一个扁平结构，后面过滤和展示都基于它。

struct BleAdvRecord { uint64_t address = 0; int16_t rssi = 0; std::string local_name; std::vector<uint8_t> manufacturer; // AD type 0xFF std::vector<uint8_t> service_data; // AD type 0x16 }; BleAdvRecord parse_adv(winrt::Windows::Devices::Bluetooth::Advertisement:: BluetoothLEAdvertisementReceivedEventArgs const& args) { BleAdvRecord rec; rec.address = args.BluetoothAddress(); // 48 位 MAC，随机地址会变 rec.rssi = args.RawSignalStrengthInDBm(); rec.local_name = winrt::to_string(args.Advertisement().LocalName()); for (auto const& sec : args.Advertisement().DataSections()) { auto type = sec.DataType(); auto data = sec.Data(); std::vector<uint8_t> buf(data.begin(), data.end()); if (type == 0xFF) { // 厂商自定义数据，常见于传感器 rec.manufacturer = std::move(buf); } else if (type == 0x16) { // Service Data，带 16 位 UUID 前缀 rec.service_data = std::move(buf); } // 0x09 完整本地名、0x08 短名已由 LocalName() 处理，不必重复解析 } return rec; }

几个 AD Type 值得记住：0x01是 Flags，0x09完整本地名，0x08短名，0x03是 16 位 Service UUID 列表，0x16是 Service Data，0xFF是厂商自定义。很多国产模组把电量、版本号塞在0xFF里，前两个字节是厂商 ID（小端），后面才是自定义内容——这个字节序如果搞反，解析出来的数值会很离谱，属于典型翻车点。

args.BluetoothAddress()拿到的是uint64_t，实际只有低 48 位有效。打印成AA:BB:CC:DD:EE:FF时要逐字节右移，别直接std::to_string，那个结果对不上任何工具。

3.2 扫描参数：Active 与 Passive 的取舍

默认构造出来的BluetoothLEAdvertisementWatcher是 Passive 模式，只收广播包，不发扫描请求。如果设备的名称放在 Scan Response 里而不是主广播包里，Passive 模式下LocalName()会是空的，你会以为设备没名字，其实是没问它。

using namespace winrt::Windows::Devices::Bluetooth::Advertisement; BluetoothLEAdvertisementWatcher watcher; // Active 会发 SCAN_REQ，能拿到 Scan Response 里的名字和额外字段 watcher.ScanningMode(BluetoothLEScanningMode::Active); // 信号强度过滤：低于 -75dBm 的直接不投递，减少回调压力 watcher.SignalStrengthFilter().InRangeThresholdInDBm(-75); watcher.SignalStrengthFilter().OutOfRangeTimeout(std::chrono::seconds(5)); watcher.SignalStrengthFilter().SamplingInterval(std::chrono::milliseconds(500)); watcher.Received([](BluetoothLEAdvertisementWatcher const&, BluetoothLEAdvertisementReceivedEventArgs const& args) { auto rec = parse_adv(args); // 这里拿到的回调在线程池线程，禁止直接碰界面 log_info("addr=%012llX rssi=%d name=%s", rec.address, rec.rssi, rec.local_name.c_str()); }); watcher.Start();

SamplingInterval控制的是信号强度采样的聚合窗口，不是扫描周期，名字容易误导。设得太小回调会很密集，设得太大 RSSI 又滞后。500ms 是个折中值，产线近距离识别场景可以再压到 200ms。

如果设备支持扩展广播（Extended Advertising），在 Win10 2004 以后可以打开AllowExtendedAdvertisements(true)，否则大包广播会被截断，你只能收到前面一小段。这个开关打不开的时候不会报错，只是数据不全，非常隐蔽。

3.3 从广播地址到连接对象

扫描到地址只是第一步，真正连上要调BluetoothLEDevice::FromBluetoothAddressAsync。这里有两个必须知道的限制：一是地址必须是 48 位的，传错位宽会直接抛异常；二是随机地址设备休眠后会换地址，你缓存下来的地址过一会儿就连不上了。

winrt::fire_and_forget connect_by_address(uint64_t addr) { using namespace winrt::Windows::Devices::Bluetooth; auto device = co_await BluetoothLEDevice::FromBluetoothAddressAsync(addr); if (!device) { log_error("connect failed, device is null"); co_return; } // 刚连上时状态可能还是 Disconnected，需要等一次 GATT 访问把它拉起来 log_info("connected=%d", (int)device.ConnectionStatus()); // 用完必须 Close，否则句柄泄漏，同一设备第二次连会失败 device.Close(); }

FromBluetoothAddressAsync返回的device为 null，通常意味着设备已经离线或者地址是随机地址且已失效，不是代码逻辑错。另一个容易忽略的点是ConnectionStatus()在刚拿到对象时常常还是Disconnected，真正触发连接的是后面第一次 GATT 访问。这个设计导致很多人在这一步加了个“连接成功”的判断，结果永远进不去分支。

4. GATT 交互：服务发现、特征读写与 Notify 订阅

4.1 服务与特征枚举的缓存策略

GetGattServicesAsync有个BluetoothCacheMode参数，取值Cached和Uncached。第一次连上设备时如果用Cached，很可能拿到空列表或者上一次的旧结构，因为系统缓存还没建立。稳妥做法是首次强制Uncached，之后可以走缓存提速。

winrt::fire_and_forget enumerate(uint64_t addr) { using namespace winrt::Windows::Devices::Bluetooth; using namespace winrt::Windows::Devices::Bluetooth::GenericAttributeProfile; auto device = co_await BluetoothLEDevice::FromBluetoothAddressAsync(addr); if (!device) co_return; // 首次必须 Uncached，强制系统去设备上真实拉一遍服务表 auto svcResult = co_await device.GetGattServicesAsync(BluetoothCacheMode::Uncached); if (svcResult.Status() != GattCommunicationStatus::Success) { log_error("get services failed, status=%d", (int)svcResult.Status()); device.Close(); co_return; } for (auto const& svc : svcResult.Services()) { auto uuid = winrt::to_string(winrt::to_hstring(svc.Uuid())); log_info("service %s", uuid.c_str()); auto charResult = co_await svc.GetCharacteristicsAsync(BluetoothCacheMode::Uncached); for (auto const& ch : charResult.Characteristics()) { auto props = ch.CharacteristicProperties(); log_info(" char %s read=%d write=%d notify=%d", winrt::to_string(winrt::to_hstring(ch.Uuid())).c_str(), (int)props.HasFlag(GattCharacteristicProperties::Read), (int)props.HasFlag(GattCharacteristicProperties::Write), (int)props.HasFlag(GattCharacteristicProperties::Notify)); } } device.Close(); }

代码里用CharacteristicProperties()先判断能力再操作，比拿到特征就写要稳。有些特征的Write属性只支持WriteWithResponse，你调了WriteWithoutResponse会返回Unreachable，报错信息很难懂。判断属性再选写入方式，能省掉一轮排查。

4.2 读写与 CCCD 订阅

订阅通知分两步：注册ValueChanged回调，然后往 CCCD（Client Characteristic Configuration Descriptor）写Notify。只注册回调不写描述符，设备根本不会推数据，这是初学者最常见的“订阅了没反应”。

winrt::fire_and_forget subscribe(GattCharacteristic ch) { using namespace winrt::Windows::Devices::Bluetooth::GenericAttributeProfile; // 回调来自线程池，不要在这里做耗时操作 auto token = ch.ValueChanged([](GattCharacteristic const&, GattValueChangedEventArgs const& args) { auto buffer = args.CharacteristicValue(); winrt::Windows::Storage::Streams::DataReader reader = winrt::Windows::Storage::Streams::DataReader::FromBuffer(buffer); std::vector<uint8_t> payload(reader.UnconsumedBufferLength()); reader.ReadBytes(payload); log_info("notify %zu bytes", payload.size()); // 交给业务层解帧，别在这里解析协议 }); // 写 CCCD，告诉设备开始推 auto status = co_await ch.WriteClientCharacteristicConfigurationDescriptorAsync( GattClientCharacteristicConfigurationDescriptorValue::Notify); if (status != GattCommunicationStatus::Success) { log_error("cccd write failed, status=%d", (int)status); } }

DataReader::FromBuffer拿到的数据长度受 MTU 限制，默认 20 字节，超过就得靠设备端分包。CCCD 写入失败最常见的原因是特征不支持 Notify，只支持 Indicate，这时候要换成Indicate枚举值，并且每条消息都要回 ACK，吞吐会明显下降。

4.3 长包分包与 MTU 协商

BLE 默认的 ATT MTU 是 23，去掉 3 字节头就是 20 字节有效载荷。要传更长的数据，得先协商 MTU，再按协商结果分包。

winrt::fire_and_forget negotiate_mtu(BluetoothLEDevice device) { using namespace winrt::Windows::Devices::Bluetooth::GenericAttributeProfile; auto session = co_await GattSession::FromDeviceIdAsync(device.BluetoothDeviceId()); // MaxPduSize 是当前协商结果，不是可设置值；实际 MTU 要减去 3 log_info("max pdu size = %d, payload <= %d", (int)session.MaxPduSize(), (int)session.MaxPduSize() - 3); session.Close(); }

要注意MaxPduSize是只读的，Windows 不提供主动发起 MTU 交换的接口，实际值由设备和系统协商决定。所以分包逻辑不能写死 20，要按运行时的值算。项目的protocol_codec.cpp里把分片和重组做成了纯函数，不碰任何 WinRT 类型，这样在 PC 上就能跑单测，不用连硬件，改协议时效率高很多。

5. 避坑与常见问题排查：只在真机上复现的那些坑

5.1 扫描阶段的三类怪现象

现象一：手机能扫到，桌面程序列表为空。原因八成是ScanningMode用了 Passive，而设备把名称和关键字段放在 Scan Response 里。解决是把模式改成Active，如果还是空，再检查SignalStrengthFilter的InRangeThresholdInDBm是不是设得太高，比如设成-40，隔着一堵墙的设备全被过滤掉了。

现象二：设备明明在广播，回调却几分钟才来一次。这是系统对广播监听的限流，同一时刻注册的 watcher 太多会被降频。解决是全局只维护一个BluetoothLEAdvertisementWatcher实例，把结果分发出去，别每个模块各建一个。

现象三：地址每次扫描都不一样。设备用的是随机私有地址，且没有做地址绑定。这类设备不能靠地址做唯一标识，得从厂商数据段里取序列号或者从设备名里提取。硬用地址做 key，重连逻辑必然失效。

5.2 连接与 GATT 阶段的翻车点

现象四：第一次能连，第二次FromBluetoothAddressAsync一直返回 null。原因是上一轮的BluetoothLEDevice对象没Close()，底层句柄还占着。解决很机械：所有BluetoothLEDevice、GattSession用完必须Close()，用 RAII 包一层最省心。这个坑我踩过不止一次，表现就是“运行一次好的，再运行就不行”，重启程序又恢复正常，很有迷惑性。

现象五：服务列表拿到了，特征列表是空的。多数是缓存问题，用Cached模式读到了半成品。解决是首次访问强制Uncached，或者在连接后先调一次GetGattServicesAsync(Uncached)把缓存刷出来，再走后续逻辑。

现象六：ValueChanged回调里访问界面直接崩。回调线程是线程池线程，不是创建 watcher 的线程。解决是用DispatcherQueue或者PostMessage把数据切回目标线程，别在回调里直接改控件。这个错误在调试器里不一定崩，Release 下才炸，属于典型的玄学问题。

注意：打包成 MSIX 分发时，清单里必须声明bluetooth能力，否则 API 调用会静默失败，不报权限错误，只是拿不到数据。

6. 二次开发：把 BLE 层和业务协议彻底剥开

接手这类代码做二次开发，最容易犯的错是直接在ValueChanged回调里写协议解析。一开始只有三条指令还行，等指令涨到二十条、还要加超时重试和状态机，那坨代码就没人敢动了。我在这个项目里坚持的分层是：gatt_client只负责“把字节送出去、把字节收回来”，protocol_codec只负责字节和结构体之间的转换，中间用一个请求队列串起来。

请求队列的关键是给每条指令配一个序号和超时。发送时把序号写进帧头，收到 Notify 后按序号匹配std::promise，超时就置为失败。这样上层调用写起来是同步的，底层还是异步的。

struct PendingRequest { uint8_t seq; std::chrono::steady_clock::time_point deadline; std::promise<std::vector<uint8_t>> promise; }; // 发送侧：分配序号、登记、写特征 std::future<std::vector<uint8_t>> send_command(GattCharacteristic ch, std::vector<uint8_t> frame) { auto req = std::make_shared<PendingRequest>(); req->seq = next_seq(); req->deadline = std::chrono::steady_clock::now() + std::chrono::seconds(2); pending_[req->seq] = req; frame[1] = req->seq; // 帧头第二字节放序号，双方约定 co_await ch.WriteValueWithResultAsync(to_buffer(frame)); return req->promise.get_future(); }

对应地，回调里按frame[1]找到pending_里的条目，set_value之后擦除。超时检查放在一个独立的定时线程里扫表，到点还没回的条目直接set_exception。这套结构加进来之后，新增一条指令只需要改protocol_codec里的一个分支，BLE 层一行不动。

验证方法我一般分三层走：先用codec_test.cpp在 PC 上跑编解码的单元测试，不接硬件；再用一个已知能工作的手机 App 对比同一设备返回的原始字节，确认解析没错；最后才上真机跑长稳，至少挂两小时看有没有句柄泄漏和内存增长。跳过前两层直接上真机，出问题时你分不清是协议错、BLE 层错还是设备固件错。

改这套代码还有个小技巧：把BluetoothCacheMode和超时时间做成配置项而不是写死。不同厂商的模组响应速度差异很大，有的 200ms 就回，有的要 1.5 秒，写死 500ms 超时在某个型号上必然误报失败。做成配置后，换模组只改一个数字。

从那以后我每次接 BLE 项目，都强制先把“扫描 → 连接 → 枚举 → 订阅 → 收发”这条链路写成最小可跑示例，跑通了再接业务逻辑，绝不把两件事混在一起调试。希望帮到你。

本文还有配套的精品资源，点击获取