openEuler分布式软总线API完全手册：从基础调用到高级功能应用

【免费下载链接】distributed-codelabsDistributed middleware code laboratory, mainly storing some application examples项目地址: https://gitcode.com/openeuler/distributed-codelabs

前往项目官网免费下载：https://ar.openeuler.org/ar/

openEuler分布式软总线是openEuler和openHarmony生态中的核心组件，提供跨设备统一通信能力，支持发现连接、设备组网和数据传输三大核心功能。本手册将帮助开发者快速掌握分布式软总线API的基础调用与高级应用技巧，轻松实现多设备间的无缝协作。

分布式软总线核心价值与架构解析

分布式软总线解决了传统多设备通信中链路复杂、协议不统一的痛点，通过抽象底层通信细节，为开发者提供标准化API接口。其核心优势包括：

• 统一通信接口：屏蔽WIFI、蓝牙等底层差异，业务层无需关心具体通信方式
• 高效设备组网：支持近场设备自动发现与组网，构建动态设备拓扑
• 多类型数据传输：提供字节、流、消息和文件等多种传输能力

组件架构概览

如架构图所示，分布式软总线系统分为四个层次：

• 应用层：提供场景化能力集与应用接口
• 分布式总线层：核心功能实现，包括组网拓扑管理、传输管理和设备发现连接
• 适配层：包含RPC框架和WLAN服务等通信适配组件
• 硬件层：WLAN、Bluetooth等物理通信介质

环境准备与基础配置

开发环境搭建

1. 获取源码

git clone https://gitcode.com/openeuler/distributed-codelabs

2. 依赖安装分布式软总线依赖distributed-utils软件包，该包已包含服务端功能，无需额外部署服务端。

3. 权限配置使用跨设备通信时，必须添加以下权限：

• ohos.permission.DISTRIBUTED_DATASYNC
• ohos.permission.DISTRIBUTED_SOFTBUS_CENTER

核心概念说明

• NetworkId：设备在组网中的唯一标识，由软总线自动分配
• Session：设备间的通信会话，是数据传输的基本单元
• Publish/Discover：设备能力发布与发现机制，用于设备间能力感知

基础API调用指南

设备发现与连接

设备发现是分布式通信的第一步，通过发布服务和发现服务实现设备间的互相感知。

发布设备能力

// 定义发布回调 IPublishCb publishCb = { .OnPublishResult = [](int publishId, PublishResult reason) { // 处理发布结果 } }; // 准备发布信息 PublishInfo info = { .publishId = 1, .capability = "com.example.myapp", .publishType = PUBLISH_TYPE_ACTIVE }; // 发布服务 int32_t ret = PublishLNN("com.example.myapp", &info, &publishCb); if (ret != SOFTBUS_OK) { // 处理发布失败 }

发现设备能力

// 定义发现回调 IRefreshCallback discoverCb = { .OnDeviceFound = [](const DeviceInfo *device) { // 处理发现的设备信息 printf("Found device: %s, networkId: %s\n", device->deviceName, device->networkId); }, .OnDiscoverResult = [](int32_t refreshId, RefreshResult reason) { // 处理发现结果 } }; // 准备发现信息 SubscribeInfo info = { .subscribeId = 1, .capability = "com.example.myapp", .subscribeType = SUBSCRIBE_TYPE_ACTIVE }; // 开始发现 int32_t ret = RefreshLNN("com.example.myapp", &info, &discoverCb); if (ret != SOFTBUS_OK) { // 处理发现失败 }

设备组网实现

组网功能实现设备间的网络连接，建立通信基础。

手动组网

// 定义组网结果回调 OnJoinLNNResult joinCallback = [](ConnectionAddr *addr, const char *networkId, int32_t retCode) { if (retCode == 0) { // 组网成功，保存networkId用于后续通信 printf("Join LNN success, networkId: %s\n", networkId); } else { // 处理组网失败 } }; // 准备连接地址（IP方式） ConnectionAddr addr = { .type = CONNECTION_ADDR_WLAN, .info = { .ip = { .ip = "192.168.1.100", .port = 5555 } } }; // 发起组网请求 int32_t ret = JoinLNN("com.example.myapp", &addr, joinCallback); if (ret != SOFTBUS_OK) { // 处理请求发送失败 }

获取组网设备信息

NodeBasicInfo *info = NULL; int32_t infoNum = 0; // 获取所有在线设备信息 int32_t ret = GetAllNodeDeviceInfo("com.example.myapp", &info, &infoNum); if (ret == 0) { for (int i = 0; i < infoNum; i++) { printf("Device %d: name=%s, networkId=%s\n", i, info[i].deviceName, info[i].networkId); } // 释放内存 FreeNodeInfo(info); }

数据传输操作

数据传输是分布式软总线的核心功能，支持多种数据类型的传输。

创建会话服务

// 定义会话回调 ISessionListener sessionListener = { .OnSessionOpened = [](int sessionId, int result) { // 会话打开回调 }, .OnSessionClosed = [](int sessionId) { // 会话关闭回调 }, .OnBytesReceived = [](int sessionId, const void *data, unsigned int dataLen) { // 字节数据接收回调 } }; // 创建会话服务 int ret = CreateSessionServer("com.example.myapp", "mySession", &sessionListener); if (ret != 0) { // 处理创建失败 }

发送字节数据

// 打开会话 int sessionId = OpenSession("mySession", "peerSession", peerNetworkId, "group1", NULL); if (sessionId <= 0) { // 处理打开会话失败 } // 发送数据 const char *data = "Hello distributed world!"; int ret = SendBytes(sessionId, data, strlen(data)); if (ret != SOFTBUS_OK) { // 处理发送失败 } // 关闭会话 CloseSession(sessionId);

高级功能应用

文件传输实现

分布式软总线支持可靠的文件传输，适用于大文件共享场景。

// 设置文件接收监听器 IFileReceiveListener recvListener = { .OnReceiveFileStarted = [](int sessionId, const char *files, int fileCnt) { // 文件接收开始回调 }, .OnReceiveFileProcess = [](int sessionId, const char *firstFile, uint64_t bytesUpload, uint64_t bytesTotal) { // 文件接收进度回调 float progress = (float)bytesUpload / bytesTotal * 100; printf("File transfer progress: %.2f%%\n", progress); }, .OnReceiveFileFinished = [](int sessionId, const char *files, int fileCnt) { // 文件接收完成回调 } }; // 设置文件接收监听 SetFileReceiveListener("com.example.myapp", "mySession", &recvListener, "/data/received"); // 发送文件 const char *sFileList[] = {"/data/file1.txt", "/data/image.jpg"}; const char *dFileList[] = {"file1.txt", "image.jpg"}; int ret = SendFile(sessionId, sFileList, dFileList, 2);

设备状态监听

通过注册设备状态回调，实时感知网络中设备的上线、下线状态。

// 定义节点状态回调 INodeStateCb nodeStateCb = { .events = EVENT_NODE_STATE_ONLINE | EVENT_NODE_STATE_OFFLINE, .onNodeOnline = [](NodeBasicInfo *info) { printf("Device online: %s, networkId: %s\n", info->deviceName, info->networkId); }, .onNodeOffline = [](NodeBasicInfo *info) { printf("Device offline: %s, networkId: %s\n", info->deviceName, info->networkId); } }; // 注册节点状态回调 RegNodeDeviceStateCb("com.example.myapp", &nodeStateCb);

分布式数据同步应用

结合分布式数据服务组件，实现多设备间数据自动同步。

实际应用场景演示

多设备组网通信示例

以下是两个设备通过分布式软总线实现组网通信的简单流程：

1. 设备A发布服务→ 2.设备B发现设备A→ 3.设备B发起组网请求→ 4.建立会话连接→ 5.数据交互

常见问题解决

分布式软总线开发中常见问题及解决方案：

1. 设备发现失败

   • 检查设备是否在同一局域网
   • 确认权限配置正确
   • 验证设备是否开启"允许被发现"开关

2. 组网连接超时

   • 检查网络稳定性
   • 确认防火墙设置是否阻止通信端口
   • 尝试使用不同的通信介质（WIFI/蓝牙）

3. 数据传输中断

   • 实现断点续传机制
   • 检查会话状态是否正常
   • 监控设备在线状态

API参考与资源

核心API速查表

相关资源

• 分布式软总线示例代码：dsoftbus/openEuler_softbus_client
• 接口详细定义：build-repo/demo/dsoftbus/interface.md
• 分布式软总线组件文档：build-repo/foundation/communication/dsoftbus/README_zh.md

通过本手册，您已掌握openEuler分布式软总线API的基础使用与高级应用技巧。分布式软总线为多设备协同提供了强大的通信能力，无论是智能家居、工业控制还是多屏互动场景，都能通过这些API快速构建高效的分布式应用。

【免费下载链接】distributed-codelabsDistributed middleware code laboratory, mainly storing some application examples项目地址: https://gitcode.com/openeuler/distributed-codelabs