linux 应通过 d-bus 调用 org.bluez.adapter1.getdevices 或 getmanagedobjects 并过滤 paired=true/trusted=true 的 org.bluez.device1 对象，而非使用 bluetoothctl；windows 需先启用适配器并检查 bth_device_info.dwvalidproperties 位掩码再读取设备名，且须调用 bluetoothfinddeviceclose 释放句柄。
Linux 下用 BlueZ 列出已配对设备：别直接调 bluetoothctl 脚本化
BlueZ 自带的 bluetoothctl 是交互式工具，不能直接用 system("bluetoothctl devices") 拿到稳定输出——它会卡在等待 agent 或超时退出，尤其在无 GUI 环境下。真要程序化读取，得走 D-Bus 接口。
关键路径是调用 org.bluez.Adapter1 的 GetDevices 方法，或监听 org.freedesktop.DBus.ObjectManager 的 GetManagedObjects。C++ 里推荐用 dbus-c++ 或原生 libdbus（前者封装稍好，后者更轻但要手动处理消息循环）。
-
GetManagedObjects返回所有蓝牙对象（含未配对但可见的），需过滤org.bluez.Device1接口且带Paired=true或Trusted=true属性的项 - 必须先调
org.bluez.Adapter1.StartDiscovery才能发现新设备，但已配对设备不依赖 discovery 状态 - 权限问题常见：
org.bluezbus 默认只允许root或lp组访问，普通用户需在/etc/dbus-1/system.d/bluetooth.conf中加 policy，或用pkexec启动（不推荐）
Windows 上用 Bluetooth API 枚举设备：别漏掉 BluetoothFindFirstDevice 的初始化步骤
Windows SDK 提供的 BluetoothFindFirstDevice / BluetoothFindNextDevice 看似简单，但实际调用前必须确保：蓝牙适配器已启用、驱动加载完成、且当前进程有设备枚举权限（UWP 限制更严，桌面应用相对宽松）。
最常踩的坑是忽略 BTH_DEVICE_INFO 结构体中 dwValidProperties 字段——它决定了哪些字段（如 szName、ulClassOfDevice）真正有效。直接读 szName 可能是空字符串，得检查对应 bit 是否置位。
立即学习“C++免费学习笔记（深入）”；
- 调用前必须用
BluetoothEnableDiscovery确保适配器处于可发现状态（否则只返回已配对设备） - 若需获取未配对但正在广播的设备，得用
BluetoothGATTEnumerateServices+ 扫描回调，不是FindFirstDevice能覆盖的场景 - 返回的
HBLUETOOTH_DEVICE_FIND句柄必须用BluetoothFindDeviceClose显式释放，否则句柄泄漏
跨平台方案为什么难做？核心差异在“设备”定义本身
Linux（BlueZ）和 Windows 对“一个蓝牙设备”的建模完全不同：BlueZ 把配对设备、远程服务、GATT 特征都作为 D-Bus 对象挂载在树形路径下；Windows 则把设备抽象为 BTH_DEVICE_INFO 结构，仅包含基础属性，服务发现需额外调 GATT API。
这意味着你没法写一套统一结构体来承载“设备列表”。比如 BlueZ 里一个设备可能有多个 org.bluez.GattService1 子对象，而 Windows 需两次调用（先找设备，再连上查 service）。强行抽象只会让错误更隐蔽。
- BlueZ 设备名来自远程设备广播的
Local NameAD 字段或配对时存储的别名；Windows 多数情况只返回注册表里缓存的名称，可能为空 - BlueZ 的 MAC 地址格式是
AA:BB:CC:DD:EE:FF，Windows 返回的是UCHAR[6]，转字符串得自己格式化 - 两者都没有提供“信号强度实时值”给枚举接口：BlueZ 需监听
PropertiesChanged信号，Windows 得用BluetoothRadioGetDeviceInfo配合轮询
调试时第一眼该看什么？先确认底层服务是否就绪
90% 的“读不到设备”问题，根源不在代码，而在系统层。别急着改 C++ 逻辑，先验证基础通路：
- Linux：运行
systemctl status bluetooth，确认bluetoothd正在运行；再用bluetoothctl list和devices手动确认能看到设备 - Windows：打开“设置→蓝牙和其他设备”，看是否显示“已配对设备”；命令行执行
powercfg /devicequery wake_armed，确认蓝牙适配器没被电源策略禁用 - 两者共性：用
hcitool dev（Linux）或netsh bluetooth show adapters（Windows）确认本地适配器存在且UP/Enabled
设备列表为空，八成不是你代码写错了，而是 bluetoothd 没起来，或者 Windows 蓝牙支持服务（bthserv）被手动停了。这些地方不先过一遍，后面所有 D-Bus 或 API 调用都是无源之水。
