mirror of https://gitee.com/openharmony/communication_dsoftbus synced 2024-12-20 16:38:24 +00:00

guolin.fei 777787f5a5 update README_zh.md

Signed-off-by: guolin.fei <1311979151@qq.com>

2022-09-15 21:10:04 +08:00

12 KiB

Raw Blame History

分布式软总线组件

分布式软总线组件
- 简介
- 系统架构
- 目录
- 约束
- 说明
  - 使用说明
- 相关仓

简介

现实中多设备间通信方式多种多样(WIFI、蓝牙等)，不同的通信方式使用差异大，导致通信问题多；同时还面临设备间通信链路的融合共享和冲突无法处理等挑战。分布式软总线实现近场设备间统一的分布式通信管理能力，提供不区分链路的设备间发现连接、组网和传输能力，主要功能如下：

发现连接：提供基于Wifi、蓝牙等通信方式的设备发现连接能力。
设备组网：提供统一的设备组网和拓扑管理能力，为数据传输提供已组网设备信息。
数据传输：提供数据传输通道，支持消息、字节、流、文件的数据传输能力。

业务方通过使用分布式软总线提供的API实现设备间的高速通信，不用关心通信细节，进而实现业务平台的高效部署与运行能力。

系统架构

图 1 分布式软总线组件架构图

//foundation/communication/dsoftbus
├── adapter               # 适配层代码
├── components            # 依赖组件代码
├── core                  # 核心代码
│   ├── adapter           # 适配层代码
│   ├── authentication    # 认证代码
│   ├── bus_center        # 组网代码
│   ├── common            # 通用代码
│   ├── connection        # 连接代码
│   ├── discovery         # 发现代码
│   ├── frame             # 框架代码
│   └── transmission      # 传输代码
├── interfaces            # 对外接口代码
├── sdk                   # 运行业务进程代码
│   ├── bus_center        # 组网代码
│   ├── discovery         # 发现代码
│   ├── frame             # 框架代码
│   └── transmission      # 传输代码
├── tests                 # 测试代码
└── tools                 # 工具代码

约束

组网设备需在同一局域网中或者距离相近的近场设备间。
组网之前，需先完成设备绑定，绑定流程参见安全子系统中说明。

说明

使用说明

须知： 使用跨设备通信时，必须添加权限ohos.permission.DISTRIBUTED_DATASYNC和ohos.permission.DISTRIBUTED_SOFTBUS_CENTER，该权限类型为 dangerous 。

设备主动发现手机时，手机需打开超级终端的允许被“附近设备”发现开关（设置-超级终端-我的设备-允许被发现-附近设备），才能被设备发现。

1、发现

发布流程

上层应用需要对外发布自身能力时，调用服务发布接口发布自身能力。

// 发布回调
typedef struct {
    /** Callback for publish result */
    void (*OnPublishResult)(int publishId, PublishResult reason);
} IPublishCb;

// 发布服务
int32_t PublishLNN(const char *pkgName, const PublishInfo *info, const IPublishCb *cb);

上层应用不再需要对外发布自身能力时，调用StopPublishLNN接口注销服务。
```
// 注销服务
int32_t StopPublishLNN(const char *pkgName, int32_t publishId);
```

发现流程

上层应用需要发现特定能力设备时，调用发现接口启动发现。

// 发现回调
typedef struct {
    /** Callback that is invoked when a device is found */
    void (*OnDeviceFound)(const DeviceInfo *device);
    /** Callback for a subscription result */
    void (*OnDiscoverResult)(int32_t refreshId, RefreshResult reason);
} IRefreshCallback;

// 发现服务
int32_t RefreshLNN(const char *pkgName, const SubscribeInfo *info, const IRefreshCallback *cb);

当软总线发现到设备时，通过回调接口通知业务所发现的设备信息。
上层应用不再需要发现时，调用StopRefreshLNN接口停止设备发现。
```
// 停止发现
int32_t StopRefreshLNN(const char *pkgName, int32_t refreshId);
```

2、组网

发起组网请求，携带组网连接地址信息，并且提供组网执行结果回调函数。

// 组网连接地址
typedef struct {
    ConnectionAddrType type;
    union {
        struct BrAddr {
            char brMac[BT_MAC_LEN];
        } br;
        struct BleAddr {
            char bleMac[BT_MAC_LEN];
            uint8_t udidHash[UDID_HASH_LEN];
        } ble;
        struct IpAddr {
            char ip[IP_STR_MAX_LEN];
            uint16_t port; 
        } ip;
    } info;
    char peerUid[MAX_ACCOUNT_HASH_LEN];
} ConnectionAddr;

// 组网连接地址类型
typedef enum {
    CONNECTION_ADDR_WLAN = 0,
    CONNECTION_ADDR_BR,
    CONNECTION_ADDR_BLE,
    CONNECTION_ADDR_ETH,
    CONNECTION_ADDR_MAX
} ConnectionAddrType;

// 组网请求执行结果回调
typedef void (*OnJoinLNNResult)(ConnectionAddr *addr, const char *networkId, int32_t retCode);

// 发起组网请求
int32_t JoinLNN(const char *pkgName, ConnectionAddr *target, OnJoinLNNResult cb);

等待组网结果，JoinLNN()返回成功表示软总线接受了组网请求，组网结果通过回调函数通知业务；组网回调函数中addr参数内容和JoinLNN()的入参互相匹配；retCode如果为0，表示组网成功，此时networkId为有效值，后续传输、退网等接口均需使用该参数；retCode如果不为0，表示组网失败，此时networkId为无效值。
使用传输相关接口进行数据传输。

发送退网请求，携带组网成功后返回的networkId，并且提供退网执行结果回调。

// 退网执行结果回调
typedef void (*OnLeaveLNNResult)(const char *networkId, int32_t retCode);

// 退网请求
int32_t LeaveLNN(const char *pkgName, const char *networkId, OnLeaveLNNResult cb);

等待退网完成，OnLeaveLNNResult()的networkId和退网请求接口中的networkId互相匹配；retCode为0表示退网成功，否则退网失败。退网成功后，networkId变为无效值，后续不应该被继续使用。

使用节点（即设备）注册和注销接口，监听网络中节点状态变化等事件。

// 事件掩码
#define EVENT_NODE_STATE_ONLINE 0x1
#define EVENT_NODE_STATE_OFFLINE 0x02
#define EVENT_NODE_STATE_INFO_CHANGED 0x04
#define EVENT_NODE_STATE_MASK 0x07

// 节点信息
typedef struct {
    char networkId[NETWORK_ID_BUF_LEN];
    char deviceName[DEVICE_NAME_BUF_LEN];
    uint16_t deviceTypeId;
} NodeBasicInfo;

// 节点状态事件回调
typedef struct {
    uint32_t events; // 组网事件掩码
    void (*onNodeOnline)(NodeBasicInfo *info);   // 节点上线事件回调
    void (*onNodeOffline)(NodeBasicInfo *info);  // 节点下线事件回调
    void (*onNodeBasicInfoChanged)(NodeBasicInfoType type, NodeBasicInfo *info); // 节点信息变化事件回调
} INodeStateCb;

//  注册节点状态事件回调
int32_t RegNodeDeviceStateCb(const char *pkgName, INodeStateCb *callback);

// 注销节点状态事件回调
int32_t UnregNodeDeviceStateCb(INodeStateCb *callback);

3、传输

创建会话服务，并设置会话相关回调，用户可在回调中处理打开/关闭和消息接收事件。

// 会话管理回调
typedef struct {
    int (*OnSessionOpened)(int sessionId, int result);
    void (*OnSessionClosed)(int sessionId);
    void (*OnBytesReceived)(int sessionId, const void *data, unsigned int dataLen);
    void (*OnMessageReceived)(int sessionId, const void *data, unsigned int dataLen);
    void (*OnStreamReceived)(int sessionId, const StreamData *data, const StreamData *ext, const StreamFrameInfo *param);
    void (*OnQosEvent)(int sessionId, int eventId, int tvCount, const QosTv *tvList);
} ISessionListener;

// 创建会话服务
int CreateSessionServer(const char *pkgName, const char *sessionName, const ISessionListener* listener);

[可选] 如果需要完成文件的发送和接收，可以注册文件传输回调，用户可在回调中处理文件发送/接收事件。

// 文件发送回调
typedef struct {
    int (*OnSendFileProcess)(int sessionId, uint64_t bytesUpload, uint64_t bytesTotal);
    int (*OnSendFileFinished)(int sessionId, const char *firstFile);
    void (*OnFileTransError)(int sessionId);
} IFileSendListener;

// 注册文件发送回调
int SetFileSendListener(const char *pkgName, const char *sessionName, const IFileSendListener *sendListener);

// 文件接收回调
typedef struct {
    int (*OnReceiveFileStarted)(int sessionId, const char *files, int fileCnt);
    int (*OnReceiveFileProcess)(int sessionId, const char *firstFile, uint64_t bytesUpload, uint64_t bytesTotal);
    void (*OnReceiveFileFinished)(int sessionId, const char *files, int fileCnt);
    void (*OnFileTransError)(int sessionId);
} IFileReceiveListener;

// 注册文件接收回调
int SetFileReceiveListener(const char *pkgName, const char *sessionName,const IFileReceiveListener *recvListener, const char *rootDir);

创建会话，用于收发数据。

// 创建会话
int OpenSession(const char *mySessionName, const char *peerSessionName, const char *peerNetworkId, const char *groupId, const SessionAttribute* attr);

通过sessionId向对端设备发送数据。

// 发送字节数据
int SendBytes(int sessionId, const void *data, unsigned int len);
// 发送消息数据
int SendMessage(int sessionId, const void *data, unsigned int len);
// 发送流数据
int SendStream(int sessionId, const StreamData *data, const StreamData *ext, const StreamFrameInfo *param);
// 发送文件
int SendFile(int sessionId, const char *sFileList[], const char *dFileList[], uint32_t fileCnt);

通过sessionId关闭会话。

// 关闭会话
void CloseSession(int sessionId);

删除会话服务。

// 删除会话服务
int RemoveSessionServer(const char *pkgName, const char *sessionName);

12 KiB Raw Blame History Unescape Escape

分布式软总线组件

简介

系统架构

目录

约束

说明

使用说明

相关仓

12 KiB

Raw Blame History