可信设备群组管理开发指导

• 场景介绍
• 接口说明
• 开发步骤
• 调测验证

场景介绍

当分布式业务需要利用软总线提供的设备间安全会话通信时，可以使用可信设备群组管理服务在设备间创建可信群组。在OpenHarmony下提供异账号下基于PIN、二维码、碰一碰等设备认证能力和同华为账号群组下的设备认证能力，分布式应用可基于该能力建立和使用设备间的安全可信关系。对于未登录华为账号的设备，可以通过PIN码输入、二维码扫描后获取的设备连接信息和PIN码信息，再通过可信设备群组管理提供的群组创建，群组成员添加，主动建立设备间可信关系；在有其它业务应用已经创建并分享了设备可信群组的情况下或者登录了相同的华为账号后，也可以通过可信设备群组管理提供的查询能力，复用这些可信群组。

接口说明

可信群组管理组件当前提供innerkits接口，仅供系统应用调用，相关接口及功能描述如下：

表 1 群组管理器提供的JAVA API接口功能介绍

表 2 群组管理器提供的C++ API，供内部系统应用通过SA查询群组信息；

开发步骤

群组管理的开发步骤比较简单，大体的流程就是先获取一个实例，获取实例的同时就注册了群组操作结果的通知回调，获取到实例后就可以对群组进行成员的添加、删除和群组的友元设置以及群组的相关的查询操作。

场景一 创建群组，下面首先以创建群组为例，说明群组管理类的创建以及接口使用方法：

private HwDeviceGroupManager hwDeviceGroupManager;
...
private HichainGroupCallback groupCallbackByA = new HichainGroupCallback() {
    @Override public void onFinish(long requestId, GroupOperation operationCode, String returnData) {

    }    
    @Override public void onError(long requestId, GroupOperation operationCode, int errorCode, String errorReturn) { 

    }    
    @Override public String onRequest(long requestId, GroupOperation operationCode, String reqParams) {
        JSONObject onRequestJson = generateConfirmation(REQUEST_ACCEPTED);       
        return onRequestJson.toString();
    }
};
...
Optional<Context> context = convertAbilityToContext(mAbility);
Context ctxt = context.get();
hwDeviceGroupManager = HwDeviceGroupManager.getInstance(ctxt, APP_ID, groupCallbackByA);
int ret = hwDeviceGroupManager.createGroup(APP_ID, GROUP_NAME, GROUP_TYPE, GROUP_INFO);

1. 在类成员里申明群组管理实例的私有成员变量

   private HwDeviceGroupManager hwDeviceGroupManager;

2. 创建一个群组管理操作回调；

   private HichainGroupCallback groupCallbackByA = new HichainGroupCallback();

3. 在构造函数里创建一个群组管理的实例, 在分布式场景中，位于不同设备的同业务应用，应该设置相同的APP_ID；

   hwDeviceGroupManager = HwDeviceGroupManager.getInstance(ctxt, APP_ID, groupCallbackByA);

4. 调用createGroup创建一个群组，当函数返回为0，在表明创建群组的请求已正确提交；

   int ret = hwDeviceGroupManager.createGroup(APP_ID, GROUP_NAME, GROUP_TYPE, GROUP_INFO);

5. 群组创建成功，会收到一个onFinish的回调，回调函数中operationCode参数为OperationCode.CREATE, 表明是创建群组操作，returnData为Json格式数据，会包含一个“groupId”的字段，返回创建的群组的Id值。

场景二 添加成员，在创建群组后，我们希望把目标设备经过设备认证加入到群组中，后续就可以通过软总线向目标设备发起可信的加密通信；

deviceGroupManager = DeviceGroupManager.getInstance(mAbility, APP_ID, hichainGroupCallback);
private static final String CONN_PARAM ="{\"DEVICE_ID\":\"11111111\",\"WIFI_IP\":\"192.168.43.149\",\"WIFI_PORT\":\"30000\",\"BLE_MAC\":\"\"}";
private static final String ADD_PARAM ="{\"groupId\":\"344C1C8B149\",\"groupName\":\"myGroup\",\"addId\":\"11111111\",\"isAdmin\":\"false\"}";
private static final int GROUP_TYPE = 256;
int result = deviceGroupManager.addMemberToGroup(APP_ID, reqId, ADD_PARAM, CONN_PARAM, GROUP_TYPE);

1. 获取群组管理的实例；

   deviceGroupManager = HwDeviceGroupManager.getInstance(mAbility, APP_ID, hichainGroupCallback);

2. 设置添加成员的网络连接参数，为JSON格式，为软总线支持的网络参数字段，包括WIFI_IP，WIFI_PORT，BLR_MAC，DEVICE_ID等，具体连接参数要求参见软总线；

   String CONN_PARAM ="{\"DEVICE_ID\":\"11111111\",\"WIFI_IP\":\"192.168.43.149\",\"WIFI_PORT\":\"30000\",\"BLE_MAC\":\"\"}";

3. 设置添加成员的成员信息参数，为JSON格式，包括欲添加的群组ID，群组名，是否是管理员，若是主动邀请对方加入，则isAdmin字段为true，若是主动加入对方群组，则isAdmin为false

   String ADD_PARAM ="{\"groupId\":\"344C1C8B149\",\"groupName\":\"myGroup\",\"addId\":\"11111111\",\"isAdmin\":\"false\"}";

4. 设置欲添加的群组的群组类型为256，即点对点群组；

   private static final int GROUP_TYPE = 256;

5. 在HichainGroupCallback 的onRequest函数，参见场景一列出的generateConfirmation传入指定的参数，其中PIN_CODE为为PIN码，由上层业务提供界面给用户输入，确保分布式场景两端设置的PIN码一致，后续步骤才能成功；

   private JSONObject generateConfirmation(int confirmation) {    
       JSONObject jsonObject = new JSONObject();    
       try {    jsonObject.put("pinCode", PIN_CODE);
                jsonObject.put("confirmation", confirmation);    
       } catch (JSONException e) {
           LogUtil.error(TAG, "" + e.getMessage());    
       }
       return jsonObject;
   }

6. 调用群组管理的添加成员接口

   result = deviceGroupManager.addMemberToGroup(APP_ID, reqId, ADD_PARAM, CONN_PARAM, GROUP_TYPE);

7. 若添加成功，将会收到HichainGroupCallback.onFinish的回调，其中operationCode参数为OperationCode.JOIN

8. 添加成员成功后，业务可以调用软总线请求创建设备间安全会话。

调测验证

1 在OpenHarmony上开发应用App。

2 根据开发指导开发，开发应用App。

3 执行创建群组操作，如果收到onFinish回调，代表创建群组成功。

4 在分布式组网的节点部署相同的App，假设当前部署的有节点A和节点B；

5 通过上层将节点B的连接参数，通过扫码的方式，传递到节点A，

6 节点A上App创建一个群组group1，节点A上App调用添加成员接口，将B加入到group1中，若收到HichainGroupCallback.onFinish，表明加入群组成功；