OpenHarmony 分布式软总线设备发现流程学习文档

本文基于分布式设备发现完整调用流程，拆解软总线设备发现全链路，覆盖 API 入口、管理模块、底层传输、事件回调、多协议适配（CoAP/NFC/BLE/Wi-Fi）、服务启停与状态分发完整逻辑，适用于鸿蒙分布式开发、软总线底层调试、设备互联原理学习。

flowchart LR
    A[业务层<br/>StartDeviceDiscovery] --> B[DiscoveryManager<br/>管理层]
    B --> C{状态校验<br/>Client/Server}
    C -->|Client 主动扫描| D[BLE Discovery]
    C -->|Client 主动扫描| E[Wi-Fi/CoAP Discovery]
    C -->|Client 主动扫描| F[NFC Discovery]
    C -->|Server 广播| G[本机信息广播]
    D --> H[OnDeviceFound<br/>逐层回调]
    E --> H
    F --> H
    G --> H
    H --> A

一、文档概述与核心概念

1.1 核心概念前置

概念	说明
DiscoveryManager	设备发现总管理类，统一对外 API、调度底层发现任务、分发设备上下线事件
SoftBus Client/Server	软总线客户端、服务端分层，客户端提供上层业务接口，服务端执行底层扫描
多传输介质	BLE 低功耗蓝牙、Wi-Fi、CoAP、NFC 为设备扫描底层通道
回调机制	OnDeviceFound/OnDeviceLost 设备上下线通知，业务层注册接收设备信息
状态机	设备发现分为启动扫描、扫描中、停止扫描三阶段，通过状态判断避免重复启停

1.2 整体流程总览

整个设备发现分为 5 大阶段：

1. 上层业务调用发现入口 API
2. DiscoveryManager 统一管理，创建/注册发现回调
3. 状态校验，区分客户端/服务端发现任务
4. 底层多协议（BLE/Wi-Fi/CoAP/NFC）启动扫描，上报设备事件
5. 底层扫描结果逐层回调分发，业务层接收设备上下线通知

二、分阶段详细流程解析

阶段 1：业务层发起设备发现（入口 API）

核心入口函数：

// 启动设备发现
int32_t StartDeviceDiscovery(const char *pkgName, const DiscoveryCallback *callback);
// 停止设备发现
int32_t StopDeviceDiscovery(const char *pkgName);

• 业务应用传入包名 pkgName + 自定义回调结构体 DiscoveryCallback（包含设备找到、设备丢失两个回调函数指针）
• 函数内部直接调用 DiscoveryManager::StartDeviceDiscovery，将上层请求转发给发现管理核心模块
• 同时保存业务传入的回调对象，用于后续底层扫描到设备时分发事件

回调结构体核心定义：

typedef struct {
    // 扫描到新设备时触发
    void (*OnDeviceFound)(const DeviceInfo *device);
    // 设备离线/扫描超时消失时触发
    void (*OnDeviceLost)(const DeviceInfo *device);
} DiscoveryCallback;

阶段 2：DiscoveryManager 管理层处理请求

DiscoveryManager 是整个发现模块中枢，承担回调注册、任务管理、状态判断、底层调度四大职责：

职责	说明
注册业务回调	将上层传入的 DiscoveryCallback 存入本地回调链表，支持多应用同时注册独立监听
校验发现状态	区分 ON_IP_CMSERVER_DEVICE_DISCOVERY / ON_IP_CMSCLIENT_DEVICE_DISCOVERY：Client 端发现 = 本地设备扫描周边远端设备；Server 端发现 = 本地设备对外广播自身信息
任务去重校验	若当前已处于扫描状态直接返回，避免重复启动多份扫描任务造成资源冲突；未扫描则创建全新 Discovery 任务
分发指令	下发启动/停止扫描指令至底层 SoftBus Discovery 模块

阶段 3：软总线底层分发——区分 Client/Server 扫描逻辑

3.1 客户端扫描（主动发现其他设备）

1. DiscoveryManager::StartDiscovery 下发扫描任务
2. 调用 SoftBus Client 客户端通道，分发扫描指令至各物理介质驱动
3. 支持多介质并行扫描：BLE、Wi-Fi、CoAP、NFC，由各自介质管理模块独立执行广播监听

3.2 服务端广播（被其他设备发现）

1. 触发分支 ON_IP_CMSSERVER_DISCOVER_START / FINISH
2. DiscoveryManager 启动本地设备广播任务，向局域网/蓝牙广播本机设备名称、设备类型、网络能力、安全校验信息
3. 停止广播时执行 Server Discovery Finish，关闭各介质广播通道

阶段 4：底层多传输介质扫描实现

每种介质独立封装扫描逻辑，统一向上上报设备事件：

介质模块	作用	扫描特性
BLE Discovery	低功耗蓝牙设备扫描	近距离、低功耗，适用于轻设备互联
Wi-Fi/CoAP Discovery	Wi-Fi 局域网设备发现	远距离、高带宽，智能家居、大屏设备
NFC Discovery	近场触碰发现	点对点触碰触发，安全配对场景

底层统一上报逻辑（所有介质通用）：

1. BLE/Wi-Fi/NFC 介质扫描到设备后，封装 DeviceInfo 结构体（设备名称、设备 ID、网络类型、能力集、信号强度）
2. 调用介质层回调 OnDeviceFound，逐层向上透传至 SoftBus 层
3. 设备超时未上报信号时，触发 OnDeviceLost 丢失事件

阶段 5：事件逐层回调分发至上层业务（反向回调链路）

扫描结果上报为自底向上逆向调用链：

介质层(BLE/Wi-Fi) OnDeviceFound
  → SoftBus 底层回调
    → DiscoveryManager 统一事件分发
      → 业务层注册的 DiscoveryCallback

• DiscoveryManager 遍历所有注册的业务回调链表，将设备信息分发给每一个监听应用
• 业务层在 OnDeviceFound 回调中获取远端设备完整信息，发起设备绑定/组网连接
• 设备离线时完整复用同一回调链路，触发业务 OnDeviceLost 做离线处理

三、关键分支逻辑：启动/停止扫描

3.1 启动扫描分支

StartDeviceDiscovery
 └─ 校验无正在运行的扫描任务
     └─ 区分 Client/Server 模式
         ├─ Client：启动 BLE/Wi-Fi 多介质扫描监听
         └─ Server：启动本机设备广播
             └─ 底层介质开启扫描，等待上报设备事件
                 └─ 设备上报后逐层回调通知业务

3.2 停止扫描分支

StopDeviceDiscovery
 └─ DiscoveryManager 标记扫描状态为停止
     └─ 下发停止指令至 BLE/Wi-Fi/NFC 各介质
         └─ 关闭广播/扫描通道，清空临时扫描缓存
             └─ 释放本次注册的回调资源
                 （多应用共存时仅销毁当前 pkgName 对应的回调）

四、核心数据结构说明

4.1 DeviceInfo 设备信息结构体

底层介质扫描后封装的设备核心数据，回调中透传给业务：

字段	说明
deviceId	设备唯一分布式 ID（跨设备身份标识）
deviceName	设备显示名称
deviceType	设备类型（手机/平板/智慧屏/穿戴设备）
networkType	发现介质（BLE/Wi-Fi/NFC）
capability	设备支持分布式能力（投屏、文件传输、多屏协同）
rssi	信号强度，用于判断设备距离

4.2 DiscoveryTask 发现任务结构体

DiscoveryManager 内部管理单条扫描任务：

字段	说明
pkgName	发起扫描的应用包名
callback	业务注册的设备上下线回调
mediaList	启用的扫描介质（BLE/Wi-Fi 组合）
isRunning	任务运行状态标记（防重复启动）

五、常见流程问题与调试要点

问题现象	原因	解决方案/排查方向
重复启动扫描报错	DiscoveryManager 状态校验检测到已存在运行中的 DiscoveryTask	启动前先调用 StopDeviceDiscovery 销毁旧任务，再重新启动
只能 BLE 扫描、Wi-Fi 设备无法发现	介质驱动未初始化/网络不通	检查 CoAP/Wi-Fi 介质驱动是否初始化、局域网是否互通、设备广播开关是否开启
扫描到设备但上层收不到 OnDeviceFound 回调	回调指针无效/任务提前释放/权限缺失	确认回调结构体指针有效、未提前调用 Stop、已申请分布式设备发现权限
设备离线延迟高	底层介质依靠心跳超时判定设备丢失	调整介质心跳上报周期，加快 OnDeviceLost 触发速度

六、双向链路时序图

sequenceDiagram
    participant App as 业务层(App)
    participant DM as DiscoveryManager
    participant SB as SoftBus底层
    participant Media as 介质层<br/>(BLE/Wi-Fi/NFC)

    App->>DM: StartDeviceDiscovery(pkgName, callback)
    DM->>DM: 状态校验 + 任务去重
    DM->>SB: 下发扫描指令
    SB->>Media: 启动多介质扫描/广播
    Media-->>SB: OnDeviceFound(DeviceInfo)
    SB-->>DM: 逐层透传设备事件
    DM-->>App: 遍历回调链表分发
    App->>DM: StopDeviceDiscovery(pkgName)
    DM->>SB: 下发停止指令
    SB->>Media: 关闭扫描/广播通道
    DM-->>App: 释放回调资源

七、流程总结

特性	说明
分层解耦	业务 API 层 → DiscoveryManager 管理层 → SoftBus 客户端/服务端 → BLE/Wi-Fi/NFC 物理介质层，层级清晰，介质可插拔扩展
双向链路	下行：业务发起 → Manager → 底层介质（启动/停止扫描）；上行：底层扫描设备事件 → 逐层回调 → 业务层接收通知
多模式支持	同时支持主动扫描其他设备（Client）和广播自身被发现（Server）
多应用隔离	基于 pkgName 隔离不同业务的回调与扫描任务，互不干扰
多传输兼容	统一上层 API，底层兼容蓝牙、Wi-Fi、NFC 多种近场通信介质，适配全场景分布式设备互联

欢迎加入Laval社区

社区规范：仅讨论OpenHarmony相关问题。