• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 分布式软总线组件<a name="ZH-CN_TOPIC_0000001103650648"></a>
2
3- [分布式软总线组件<a name="ZH-CN_TOPIC_0000001103650648"></a>](#分布式软总线组件)
4  - [简介<a name="section13587125816351"></a>](#简介)
5  - [系统架构<a name="section13587185873516"></a>](#系统架构)
6  - [目录<a name="section161941989596"></a>](#目录)
7  - [约束<a name="section119744591305"></a>](#约束)
8  - [说明<a name="section1312121216216"></a>](#说明)
9    - [使用说明<a name="section1698318421816"></a>](#使用说明)
10  - [相关仓<a name="section1371113476307"></a>](#相关仓)
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![](figures/dsoftbus-architecture_zh.png)
25**图 1**  分布式软总线组件架构图<a name="fig4460722185514"></a>
26
27## 目录<a name="section161941989596"></a>
28
29分布式软总线组件主要代码目录结构如下：
30
31```text
32//foundation/communication/dsoftbus
33├── adapter               # 适配层代码
34├── components            # 依赖组件代码
35├── core                  # 核心代码
36│   ├── adapter           # 适配层代码
37│   ├── authentication    # 认证代码
38│   ├── bus_center        # 组网代码
39│   ├── common            # 通用代码
40│   ├── connection        # 连接代码
41│   ├── discovery         # 发现代码
42│   ├── frame             # 框架代码
43│   └── transmission      # 传输代码
44├── interfaces            # 对外接口代码
45├── sdk                   # 运行业务进程代码
46│   ├── bus_center        # 组网代码
47│   ├── discovery         # 发现代码
48│   ├── frame             # 框架代码
49│   └── transmission      # 传输代码
50├── tests                 # 测试代码
51└── tools                 # 工具代码
52```
53
54## 约束<a name="section119744591305"></a>
55
56-   组网设备需在同一局域网中 或者 距离相近的近场设备间。
57-   组网之前，需先完成设备绑定，绑定流程参见安全子系统中说明。
58
59## 说明<a name="section1312121216216"></a>
60
61### 使用说明<a name="section1698318421816"></a>
62
63>**须知：**
64>使用跨设备通信时，必须添加权限`ohos.permission.DISTRIBUTED_DATASYNC`和`ohos.permission.DISTRIBUTED_SOFTBUS_CENTER`，该权限类型为 _**dangerous**_ 。
65
66>设备主动发现手机时，手机需打开超级终端的允许被“附近设备”发现开关（设置-超级终端-我的设备-允许被发现-附近设备），才能被设备发现。
67
68**1、发现**
69
70-   **发布流程**
71
721.  上层应用需要对外发布自身能力时，调用服务发布接口发布自身能力。
73
74    ```C
75    // 发布回调
76    typedef struct {
77        /** Callback for publish result */
78        void (*OnPublishResult)(int publishId, PublishResult reason);
79    } IPublishCb;
80
81    // 发布服务
82    int32_t PublishLNN(const char *pkgName, const PublishInfo *info, const IPublishCb *cb);
83    ```
84
852.  上层应用不再需要对外发布自身能力时，调用StopPublishLNN接口注销服务。
86
87    ```C
88    // 注销服务
89    int32_t StopPublishLNN(const char *pkgName, int32_t publishId);
90    ```
91
92
93-   **发现流程**
94
951.  上层应用需要发现特定能力设备时，调用发现接口启动发现。
96
97    ```C
98    // 发现回调
99    typedef struct {
100        /** Callback that is invoked when a device is found */
101        void (*OnDeviceFound)(const DeviceInfo *device);
102        /** Callback for a subscription result */
103        void (*OnDiscoverResult)(int32_t refreshId, RefreshResult reason);
104    } IRefreshCallback;
105
106    // 发现服务
107    int32_t RefreshLNN(const char *pkgName, const SubscribeInfo *info, const IRefreshCallback *cb);
108    ```
109
1102.  当软总线发现到设备时，通过回调接口通知业务所发现的设备信息。
1113.  上层应用不再需要发现时，调用StopRefreshLNN接口停止设备发现。
112
113    ```C
114    // 停止发现
115    int32_t StopRefreshLNN(const char *pkgName, int32_t refreshId);
116    ```
117
118**2、组网**
119
1201.  发起组网请求，携带组网连接地址信息，并且提供组网执行结果回调函数。
121
122    ```C
123    // 组网连接地址
124    typedef struct {
125        ConnectionAddrType type;
126        union {
127            struct BrAddr {
128                char brMac[BT_MAC_LEN];
129            } br;
130            struct BleAddr {
131                char bleMac[BT_MAC_LEN];
132                uint8_t udidHash[UDID_HASH_LEN];
133            } ble;
134            struct IpAddr {
135                char ip[IP_STR_MAX_LEN];
136                uint16_t port;
137            } ip;
138        } info;
139        char peerUid[MAX_ACCOUNT_HASH_LEN];
140    } ConnectionAddr;
141
142    // 组网连接地址类型
143    typedef enum {
144        CONNECTION_ADDR_WLAN = 0,
145        CONNECTION_ADDR_BR,
146        CONNECTION_ADDR_BLE,
147        CONNECTION_ADDR_ETH,
148        CONNECTION_ADDR_MAX
149    } ConnectionAddrType;
150
151    // 组网请求执行结果回调
152    typedef void (*OnJoinLNNResult)(ConnectionAddr *addr, const char *networkId, int32_t retCode);
153
154    // 发起组网请求
155    int32_t JoinLNN(const char *pkgName, ConnectionAddr *target, OnJoinLNNResult cb);
156    ```
157
1582.  等待组网结果，JoinLNN\(\)返回成功表示软总线接受了组网请求，组网结果通过回调函数通知业务；组网回调函数中addr参数内容和JoinLNN\(\)的入参互相匹配；retCode如果为0，表示组网成功，此时networkId为有效值，后续传输、退网等接口均需使用该参数；retCode如果不为0，表示组网失败，此时networkId为无效值。
1593.  使用传输相关接口进行数据传输。
1604.  发送退网请求，携带组网成功后返回的networkId，并且提供退网执行结果回调。
161
162    ```C
163    // 退网执行结果回调
164    typedef void (*OnLeaveLNNResult)(const char *networkId, int32_t retCode);
165
166    // 退网请求
167    int32_t LeaveLNN(const char *pkgName, const char *networkId, OnLeaveLNNResult cb);
168    ```
169
1705.  等待退网完成，OnLeaveLNNResult\(\)的networkId和退网请求接口中的networkId互相匹配；retCode为0表示退网成功，否则退网失败。退网成功后，networkId变为无效值，后续不应该被继续使用。
1716.  使用节点（即设备）注册和注销接口，监听网络中节点状态变化等事件。
172
173    ```C
174    // 事件掩码
175    #define EVENT_NODE_STATE_ONLINE 0x1
176    #define EVENT_NODE_STATE_OFFLINE 0x02
177    #define EVENT_NODE_STATE_INFO_CHANGED 0x04
178    #define EVENT_NODE_STATUS_CHANGED 0x08
179    #define EVENT_NODE_STATE_MASK 0xF
180
181    // 节点信息
182    typedef struct {
183        char networkId[NETWORK_ID_BUF_LEN];
184        char deviceName[DEVICE_NAME_BUF_LEN];
185        uint16_t deviceTypeId;
186    } NodeBasicInfo;
187
188    // 节点状态事件回调
189    typedef struct {
190        uint32_t events; // 组网事件掩码
191        void (*onNodeOnline)(NodeBasicInfo *info);   // 节点上线事件回调
192        void (*onNodeOffline)(NodeBasicInfo *info);  // 节点下线事件回调
193        void (*onNodeBasicInfoChanged)(NodeBasicInfoType type, NodeBasicInfo *info); // 节点信息变化事件回调
194        void (*onNodeStatusChanged)(NodeStatusType type, NodeStatus *status); // 设备运行状态变化事件回调
195    } INodeStateCb;
196
197    //  注册节点状态事件回调
198    int32_t RegNodeDeviceStateCb(const char *pkgName, INodeStateCb *callback);
199
200    // 注销节点状态事件回调
201    int32_t UnregNodeDeviceStateCb(INodeStateCb *callback);
202    ```
203
204**3、传输**
205
2061.  创建会话服务，并设置会话相关回调，用户可在回调中处理打开/关闭和消息接收事件。
207
208    ```C
209    // 会话管理回调
210    typedef struct {
211        int (*OnSessionOpened)(int sessionId, int result);
212        void (*OnSessionClosed)(int sessionId);
213        void (*OnBytesReceived)(int sessionId, const void *data, unsigned int dataLen);
214        void (*OnMessageReceived)(int sessionId, const void *data, unsigned int dataLen);
215        void (*OnStreamReceived)(int sessionId, const StreamData *data, const StreamData *ext, const StreamFrameInfo *param);
216        void (*OnQosEvent)(int sessionId, int eventId, int tvCount, const QosTv *tvList);
217    } ISessionListener;
218
219    // 创建会话服务
220    int CreateSessionServer(const char *pkgName, const char *sessionName, const ISessionListener* listener);
221    ```
222
2232.  [可选] 如果需要完成文件的发送和接收，可以注册文件传输回调， 用户可在回调中处理文件发送/接收事件。
224
225    ```C
226    // 文件发送回调
227    typedef struct {
228        int (*OnSendFileProcess)(int sessionId, uint64_t bytesUpload, uint64_t bytesTotal);
229        int (*OnSendFileFinished)(int sessionId, const char *firstFile);
230        void (*OnFileTransError)(int sessionId);
231    } IFileSendListener;
232
233    // 注册文件发送回调
234    int SetFileSendListener(const char *pkgName, const char *sessionName, const IFileSendListener *sendListener);
235
236    // 文件接收回调
237    typedef struct {
238        int (*OnReceiveFileStarted)(int sessionId, const char *files, int fileCnt);
239        int (*OnReceiveFileProcess)(int sessionId, const char *firstFile, uint64_t bytesUpload, uint64_t bytesTotal);
240        void (*OnReceiveFileFinished)(int sessionId, const char *files, int fileCnt);
241        void (*OnFileTransError)(int sessionId);
242    } IFileReceiveListener;
243
244    // 注册文件接收回调
245    int SetFileReceiveListener(const char *pkgName, const char *sessionName,const IFileReceiveListener *recvListener, const char *rootDir);
246    ```
247
2483.  创建会话 ，用于收发数据。
249
250    ```C
251    // 创建会话
252    int OpenSession(const char *mySessionName, const char *peerSessionName, const char *peerNetworkId, const char *groupId, const SessionAttribute* attr);
253    ```
254
2554. 通过sessionId向对端设备发送数据。
256
257    ```C
258    // 发送字节数据
259    int SendBytes(int sessionId, const void *data, unsigned int len);
260    // 发送消息数据
261    int SendMessage(int sessionId, const void *data, unsigned int len);
262    // 发送流数据
263    int SendStream(int sessionId, const StreamData *data, const StreamData *ext, const StreamFrameInfo *param);
264    // 发送文件
265    int SendFile(int sessionId, const char *sFileList[], const char *dFileList[], uint32_t fileCnt);
266    ```
267
2685. 通过sessionId关闭会话。
269
270    ```C
271    // 关闭会话
272    void CloseSession(int sessionId);
273    ```
274
2756. 删除会话服务。
276
277    ```C
278    // 删除会话服务
279    int RemoveSessionServer(const char *pkgName, const char *sessionName);
280    ```
281
282## 相关仓<a name="section1371113476307"></a>
283
284[分布式软总线子系统](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/%E5%88%86%E5%B8%83%E5%BC%8F%E8%BD%AF%E6%80%BB%E7%BA%BF%E5%AD%90%E7%B3%BB%E7%BB%9F.md)
285
286**communication_dsoftbus**
287
288[communication_bluetooth](https://gitee.com/openharmony/communication_bluetooth)
289
290[communication_ipc](https://gitee.com/openharmony/communication_ipc)
291
292[communication_wifi](https://gitee.com/openharmony/communication_wifi)
293