簡介

現實中多設備間通信方式多種多樣(WIFI、藍牙等)，不同的通信方式使用差異大，導致通信問題多；同時還面臨設備間通信鏈路的融合共享和沖突無法處理等挑戰。分布式軟總線實現近場設備間統一的分布式通信管理能力，提供不區分鏈路的設備間發現連接、組網和傳輸能力，主要功能如下：

• 發現連接：提供基于Wifi、藍牙等通信方式的設備發現連接能力。
• 設備組網：提供統一的設備組網和拓撲管理能力，為數據傳輸提供已組網設備信息。
• 數據傳輸：提供數據傳輸通道，支持消息、字節、流、文件的數據傳輸能力。

業務方通過使用分布式軟總線提供的API實現設備間的高速通信，不用關心通信細節，進而實現業務平臺的高效部署與運行能力。

系統架構

圖 1 分布式軟總線組件架構圖

約束

• 組網設備需在同一局域網中 或者 距離相近的近場設備間。
• 組網之前，需先完成設備綁定，綁定流程參見安全子系統中說明。
• 傳輸完成數據收發之后，業務要主動關閉會話，釋放資源。

說明

使用說明

須知： 使用跨設備通信時，必須添加權限ohos.permission.DISTRIBUTED_DATASYNC和ohos.permission.DISTRIBUTED_SOFTBUS_CENTER，該權限類型為 dangerous 。

設備主動發現手機時，手機需打開超級終端的允許被“附近設備”發現開關（設置-超級終端-我的設備-允許被發現-附近設備），才能被設備發現。

1、發現

• 發布流程

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);
   

2. 上層應用不再需要對外發布自身能力時，調用StopPublishLNN接口注銷服務。

   // 注銷服務
   int32_t StopPublishLNN(const char *pkgName, int32_t publishId);
   

• 發現流程

1. 上層應用需要發現特定能力設備時，調用發現接口啟動發現。

   // 發現回調
   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);
   

2. 當軟總線發現到設備時，通過回調接口通知業務所發現的設備信息。
3. 上層應用不再需要發現時，調用StopRefreshLNN接口停止設備發現。

   // 停止發現
   int32_t StopRefreshLNN(const char *pkgName, int32_t refreshId);
   

2、組網

1. 發起組網請求，攜帶組網連接地址信息，并且提供組網執行結果回調函數。

   // 組網連接地址
   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);
   

2. 等待組網結果，JoinLNN()返回成功表示軟總線接受了組網請求，組網結果通過回調函數通知業務；組網回調函數中addr參數內容和JoinLNN()的入參互相匹配；retCode如果為0，表示組網成功，此時networkId為有效值，后續傳輸、退網等接口均需使用該參數；retCode如果不為0，表示組網失敗，此時networkId為無效值。
3. 使用傳輸相關接口進行數據傳輸。
4. 發送退網請求，攜帶組網成功后返回的networkId，并且提供退網執行結果回調。

   // 退網執行結果回調
   typedef void (*OnLeaveLNNResult)(const char *networkId, int32_t retCode);
   
   // 退網請求
   int32_t LeaveLNN(const char *pkgName, const char *networkId, OnLeaveLNNResult cb);
   

5. 等待退網完成，OnLeaveLNNResult()的networkId和退網請求接口中的networkId互相匹配；retCode為0表示退網成功，否則退網失敗。退網成功后，networkId變為無效值，后續不應該被繼續使用。
6. 使用節點（即設備）注冊和注銷接口，監聽網絡中節點狀態變化等事件。

   // 事件掩碼
   #define EVENT_NODE_STATE_ONLINE 0x1
   #define EVENT_NODE_STATE_OFFLINE 0x02
   #define EVENT_NODE_STATE_INFO_CHANGED 0x04
   #define EVENT_NODE_STATUS_CHANGED 0x08
   #define EVENT_NODE_STATE_MASK 0xF
   
   // 節點信息
   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); // 節點信息變化事件回調
       void (*onNodeStatusChanged)(NodeStatusType type, NodeStatus *status); // 設備運行狀態變化事件回調
   } INodeStateCb;
   
   //  注冊節點狀態事件回調
   int32_t RegNodeDeviceStateCb(const char *pkgName, INodeStateCb *callback);
   
   // 注銷節點狀態事件回調
   int32_t UnregNodeDeviceStateCb(INodeStateCb *callback);
   

3、傳輸

1. 創建Socket。

   typedef struct {
       char *name;                 // 本端Socket名稱
       char *peerName;             // 對端Socket名稱
       char *peerNetworkId;        // 對端Socket的網絡ID
       char *pkgName;              // 調用者包名
       TransDataType dataType;     // 傳輸的數據類型，需要與發送方法一致
   } SocketInfo;
   
   // 創建Socket
   int32_t Socket(SocketInfo info);
   

2. 服務端啟動監聽，客戶端進行綁定。

   // Socket回調函數
   typedef struct {
       void (*OnBind)(int32_t socket, PeerSocketInfo info);
       void (*OnShutdown)(int32_t socket, ShutdownReason reason);
       void (*OnBytes)(int32_t socket, const void *data, uint32_t dataLen);
       void (*OnMessage)(int32_t socket, const void *data, uint32_t dataLen);
       void (*OnStream)(int32_t socket, const StreamData *data, const StreamData *ext, const StreamFrameInfo *param);
       void (*OnFile)(int32_t socket, FileEvent *event);
       void (*OnQos)(int32_t socket, QoSEvent eventId, const QosTV *qos, uint32_t qosCount);
   } ISocketListener;
   
   typedef enum {
       QOS_TYPE_MIN_BW,            // 最小帶寬
       QOS_TYPE_MAX_LATENCY,       // 最大建鏈時延
       QOS_TYPE_MIN_LATENCY,       // 最小建鏈時延
       QOS_TYPE_MAX_WAIT_TIMEOUT,  // 最大超時時間
       QOS_TYPE_MAX_BUFFER,        // 最大緩存
       QOS_TYPE_FIRST_PACKAGE,     // 首包大小
       QOS_TYPE_MAX_IDLE_TIMEOUT,  // 最大空閑時間
       QOS_TYPE_TRANS_RELIABILITY, // 傳輸可靠性
       QOS_TYPE_BUTT,
   } QosType;
   
   typedef struct {
       QosType qos;
       int32_t value;
   } QosTV;
   
   // 監聽Socket，由服務端開啟。
   int32_t Listen(int32_t socket, const QosTV qos[], uint32_t qosCount, const ISocketListener *listener);
   
   // 綁定Socket，由客戶端開啟。
   int32_t Bind(int32_t socket, const QosTV qos[], uint32_t qosCount, const ISocketListener *listener);
   

3. 通過Socket向對端設備發送數據。

   // 發送字節數據
   int32_t SendBytes(int32_t socket, const void *data, uint32_t len);
   // 發送消息數據
   int32_t SendMessage(int32_t socket, const void *data, uint32_t len);
   // 發送流數據# 分布式軟總線組件
   int32_t SendStream(int32_t socket, const StreamData *data, const StreamData *ext, const StreamFrameInfo *param);
   // 發送文件
   int32_t SendFile(int32_t socket, const char *sFileList[], const char *dFileList[], uint32_t fileCnt);
   

4. 關閉Socket。

   // 關閉Socket
   void Shutdown(int32_t socket);
   

審核編輯 黃宇