1# 分布式软总线组件<a name="ZH-CN_TOPIC_0000001103650648"></a> 2 3- [简介](#section13587125816351) 4- [系统架构](#section13587185873516) 5- [目录](#section161941989596) 6- [约束](#section119744591305) 7- [说明](#section1312121216216) 8 - [使用说明](#section1698318421816) 9 10- [相关仓](#section1371113476307) 11 12## 简介<a name="section13587125816351"></a> 13 14现实中多设备间通信方式多种多样\(WIFI、蓝牙等\)，不同的通信方式使用差异大，导致通信问题多；同时还面临设备间通信链路的融合共享和冲突无法处理等挑战。分布式软总线实现近场设备间统一的分布式通信管理能力，提供不区分链路的设备间发现连接、组网和传输能力，主要功能如下： 15 16- 发现连接：提供基于Wifi、蓝牙等通信方式的设备发现连接能力。 17- 设备组网：提供统一的设备组网和拓扑管理能力，为数据传输提供已组网设备信息。 18- 数据传输：提供数据传输通道，支持消息、字节数据传输等能力。 19 20业务方通过使用分布式软总线提供的API实现设备间的高速通信，不用关心通信细节，进而实现业务平台的高效部署与运行能力。 21 22## 系统架构<a name="section13587185873516"></a> 23 24**图 1** 分布式软总线组件架构图<a name="fig4460722185514"></a> 25 26 27 28 29## 目录<a name="section161941989596"></a> 30 31分布式软总线组件主要代码目录结构如下： 32 33``` 34/foundation/communication/dsoftbus 35├── interfaces # 接口代码 36├── adapter # 适配层代码 37├── core # 核心代码 38│ ├── common # 通用代码 39│ ├── authentication # 认证代码 40│ ├── bus_center # 组网代码 41│ ├── connection # 连接代码 42│ ├── discovery # 发现代码 43│ ├── transmission # 传输代码 44│ └── frame # 框架代码 45├── sdk # 运行业务进程代码 46│ ├── bus_center # 组网代码 47│ ├── discovery # 发现代码 48│ ├── transmission # 传输代码 49│ └── frame # 框架代码 50└── components # 依赖组件代码 51``` 52 53## 约束<a name="section119744591305"></a> 54 55- 组网设备需在同一局域网中。 56- 组网之前，需先完成设备绑定，绑定流程参见安全子系统中说明。 57 58## 说明<a name="section1312121216216"></a> 59 60### 使用说明<a name="section1698318421816"></a> 61 62>**须知：** 63>使用跨设备通信时，必须添加权限ohos.permission.DISTRIBUTED\_DATASYNC，该权限类型为 _**dangerous**_ 。 64 65>设备主动发现手机时,手机需打开超级终端的允许被“附近设备”发现开关（设置-超级终端-我的设备-允许被发现-附近设备），才能被设备发现。 66 67**1、发现** 68 69- **发布流程** 70 711. 上层应用需要对外发布自身能力时，调用服务发布接口发布自身能力。 72 73 ``` 74 // 发布回调 75 typedef struct { 76 void (*OnPublishSuccess)(int publishId); //发布成功时回调 77 void (*OnPublishFail)(int publishId, PublishFailReason reason);//发布失败时回调 78 } IPublishCallback; 79 80 // 发布服务 81 int PublishService(const char *pkgName, const PublishInfo *info, const IPublishCallback *cb); 82 ``` 83 842. 上层应用不再需要对外发布自身能力时，调用UnpublishService接口注销服务。 85 86 ``` 87 // 注销服务 88 int UnPublishService(const char *pkgName, int publishId); 89 ``` 90 91 92- **发现流程** 93 941. 上层应用需要发现特定能力设备时，调用发现接口启动发现。 95 96 ``` 97 // 发现回调 98 typedef struct { 99 void (*OnDeviceFound)(const DeviceInfo *device); //发现设备回调 100 void (*OnDiscoverFailed)(int subscribeId, DiscoveryFailReason failReason); //启动发现失败回调 101 void (*OnDiscoverySuccess)(int subscribeId); //启动发现成功回调 102 } IDiscoveryCallback; 103 104 // 发现服务 105 int StartDiscovery(const char *pkgName, const SubscribeInfo *info, const IDiscoveryCallback *cb); 106 ``` 107 1082. 当软总线发现到设备时，通过回调接口通知业务所发现的设备信息。 1093. 上层应用不再需要发现时，调用StopDiscovery接口停止设备发现。 110 111 ``` 112 // 停止服务 113 int StopDiscovery(const char *pkgName, int subscribeId); 114 ``` 115 116 117**2、组网** 118 1191. 发起组网请求，携带组网连接地址信息，并且提供组网执行结果回调函数。 120 121 ``` 122 // 组网连接地址 123 typedef struct { 124 ConnectionAddrType type; 125 union { 126 struct BrAddr { 127 char brMac[BT_MAC_LEN]; 128 } br; 129 struct BleAddr { 130 char bleMac[BT_MAC_LEN]; 131 } ble; 132 struct IpAddr { 133 char ip[IP_STR_MAX_LEN]; 134 int port; 135 } ip; 136 } info; 137 } ConnectionAddr; 138 139 // 组网连接地址类型 140 typedef enum { 141 CONNECTION_ADDR_WLAN = 0, 142 CONNECTION_ADDR_BR, 143 CONNECTION_ADDR_BLE, 144 CONNECTION_ADDR_ETH, 145 CONNECTION_ADDR_MAX 146 } ConnectionAddrType; 147 148 // 组网请求执行结果回调 149 typedef void (*OnJoinLNNResult)(ConnectionAddr *addr, const char *networkId, int32_t retCode); 150 151 // 发起组网请求 152 int32_t JoinLNN(ConnectionAddr *target, OnJoinLNNResult cb); 153 ``` 154 1552. 等待组网结果，JoinLNN\(\)返回成功表示软总线接受了组网请求，组网结果通过回调函数通知业务；组网回调函数中addr参数内容和JoinLNN\(\)的入参互相匹配；retCode如果为0，表示组网成功，此时networkId为有效值，后续传输、退网等接口均需使用该参数；retCode如果不为0，表示组网失败，此时networkId为无效值。 1563. 使用传输相关接口进行数据传输。 1574. 发送退网请求，携带组网成功后返回的networkId，并且提供退网执行结果回调。 158 159 ``` 160 // 退网执行结果回调 161 typedef void (*OnLeaveLNNResult)(const char *networkId, int32_t retCode); 162 163 // 退网请求 164 int32_t LeaveLNN(const char *networkId, OnLeaveLNNResult cb); 165 ``` 166 1675. 等待退网完成，OnLeaveLNNResult\(\)的networkId和退网请求接口中的networkId互相匹配；retCode为0表示退网成功，否则退网失败。退网成功后，networkId变为无效值，后续不应该被继续使用。 1686. 使用节点（即设备）注册和注销接口，监听网络中节点状态变化等事件。 169 170 ``` 171 // 事件掩码 172 #define EVENT_NODE_STATE_ONLINE 0x1 173 #define EVENT_NODE_STATE_OFFLINE 0x02 174 #define EVENT_NODE_STATE_INFO_CHANGED 0x04 175 #define EVENT_NODE_STATE_MASK 0x07 176 177 // 节点信息 178 typedef struct { 179 char networkId[NETWORK_ID_BUF_LEN]; 180 char deviceName[DEVICE_NAME_BUF_LEN]; 181 uint16_t deviceTypeId; 182 } NodeBasicInfo; 183 184 // 节点状态事件回调 185 typedef struct { 186 uint32_t events; // 组网事件掩码 187 void (*onNodeOnline)(NodeBasicInfo *info); // 节点上线事件回调 188 void (*onNodeOffline)(NodeBasicInfo *info); // 节点下线事件回调 189 void (*onNodeBasicInfoChanged)(NodeBasicInfoType type, NodeBasicInfo *info); // 节点信息变化事件回调 190 } INodeStateCb; 191 192 // 注册节点状态事件回调 193 int32_t RegNodeDeviceStateCb(INodeStateCb *callback); 194 195 // 注销节点状态事件回调 196 int32_t UnregNodeDeviceStateCb(INodeStateCb *callback); 197 ``` 198 199 200**3、传输** 201 2021. 创建会话服务，并设置会话相关回调，用户可在回调中处理打开/关闭和消息接收事件。 203 204 ``` 205 // 会话管理回调 206 typedef struct { 207 int (*OnSessionOpened)(int sessionId, int result); 208 void (*OnSessionClosed)(int sessionId); 209 void (*OnBytesReceived)(int sessionId, const void *data, unsigned int dataLen); 210 void (*OnMessageReceived)(int sessionId, const void *data, unsigned int dataLen); 211 } ISessionListener; 212 213 // 创建会话服务 214 int CreateSessionServer(const char *pkgName, const char *sessionName, const ISessionListener* listener); 215 ``` 216 2172. 创建会话 ，用于收发数据。 218 219 ``` 220 // 创建会话 221 int OpenSession(const char *mySessionName, const char *peerSessionName, const char *peerDeviceId, const char *groupId, const SessionAttribute* attr); 222 ``` 223 2243. 通过sessionId向对端设备发送数据。 225 226 ``` 227 // 发送字节数据 228 int SendBytes(int sessionId, const void *data, unsigned int len); 229 // 发送消息数据 230 int SendMessage(int sessionId, const void *data, unsigned int len); 231 ``` 232 2334. 通过sessionId关闭会话。 234 235 ``` 236 // 关闭会话 237 void CloseSession(int sessionId); 238 ``` 239 2405. 删除会话服务。 241 242 ``` 243 // 删除会话服务 244 int RemoveSessionServer(const char *pkgName, const char *sessionName); 245 ``` 246 247 248## 相关仓<a name="section1371113476307"></a> 249 250分布式软总线子系统 251 252**communication_dsoftbus** 253 254communication_bluetooth 255 256communication_ipc 257 258communication_wifi 259
