1# 分布式设备管理开发指南
2
3## 分布式设备管理简介
4
5随着用户不同种类的终端设备数量不断增多，将不同设备作为本端设备能力的扩展，使设备之间协同合作完成各种复杂场景即为设备的分布式业务。
6
7分布式设备管理是分布式业务入口，在分布式业务中对周边可信和非可信设备进行统一管理。
8
9分布式设备管理提供如下四大功能：
10
11- **发现**<br/>
12  发现周围终端设备并上报。周围设备需要连接同局域网或者同时打开蓝牙，可以根据设备类型、距离、设备是否可信等进行筛选。
13
14- **绑定**<br/>
15  不同设备协同合作完成分布式业务的前提是设备间可信，对于周边发现的不可信设备，可通过绑定使彼此建立可信关系，提供pin码、碰、扫、靠等设备认证框架，支持对接各种认证交互接口。
16
17- **查询**<br/>
18  查询功能包含：查询本机设备信息、查询周围的在线的可信设备、查询可信设备信息。
19
20- **监听**<br/>
21  监听设备上、下线。设备上线表示设备间已经可信，业务可以发起分布式操作；设备下线表示分布业务不可用。
22
23### 运作机制
24
25  设备管理作为分布式业务入口，需要应用在所使用的业务场景，向发现设备主动发起绑定建立可信关系；业务结束后由业务自主判断是否解除绑定关系，设备间可信关系的解除由业务自己控制。
26
27### 约束与限制
28
29  使用设备管理能力，需要用户确认不同设备已连接同一局域网或者蓝牙开关已开启，否则该能力不可用。
30
31  设备信息属于用户敏感数据，所以即使用户已连接同一局域网或者蓝牙开关已开启，应用在获取设备位置前仍需向用户申请数据同步权限。在用户确认允许后，系统才会向应用提供设备管理能力。
32
33## 申请分布式数据同步权限开发指导
34
35### 场景概述
36
37应用在使用分布式设备管理系统能力前，需要检查是否已经获取用户授权访问分布式数据同步信息。如未获得授权，可以向用户申请需要的分布式数据同步权限。
38
39ohos.permission.DISTRIBUTED_DATASYNC：分布式数据同步权限
40
41使用设备管理能力，必须申请权限，并且获得用户授权。
42
43### 开发步骤
44
45适用于Stage应用模型。
46
471. 在module.json5配置文件中配置分布式数据同步权限ohos.permission.DISTRIBUTED_DATASYNC。
48
49   ```ts
50   {
51     "module" : {
52       "requestPermissions":[
53         {
54           "name" : "ohos.permission.DISTRIBUTED_DATASYNC",
55           "reason": "$string:distributed_permission",
56           "usedScene": {
57             "abilities": [
58               "MainAbility"
59             ],
60             "when": "inuse"
61           }
62         }
63       ]
64     }
65   }
66   ```
672. 导入common和abilityAccessCtrl模块，用于获取权限申请的能力。
68
69   ```ts
70   import { common, abilityAccessCtrl } from '@kit.AbilityKit';
71   ```
72
733. 分布式数据同步权限的授权方式为user_grant，因此需要调用requestPermissionsFromUser接口，以动态弹窗的方式向用户申请授权。
74
75   ```ts
76   let context = getContext(this) as common.UIAbilityContext;
77   let atManager = abilityAccessCtrl.createAtManager();
78   try {
79     atManager.requestPermissionsFromUser(context, ['ohos.permission.DISTRIBUTED_DATASYNC']).then((data) => {
80       console.log('data: ' + JSON.stringify(data));
81     }).catch((err: object) => {
82       console.log('err: ' + JSON.stringify(err));
83     })
84   } catch (err) {
85     console.log('catch err->' + JSON.stringify(err));
86   }
87   ```
88
89## 设备发现开发指导
90
91### 场景概述
92
93开发者可以调用DeviceManager设备发现相关接口，获取周边可用的设备。
94
95### 接口说明
96
97startDiscovering(discoverParam: {[key:&nbsp;string]:&nbsp;Object;} , filterOptions?: {[key:&nbsp;string]:&nbsp;Object;} ): void;
98
99发现周边同局域网或者开启蓝牙的设备。详细信息参见：[startDiscovering](../reference/apis-distributedservice-kit/js-apis-distributedDeviceManager.md#startdiscovering)。
100
101
102### 开发步骤
103
1041. 申请分布式数据同步权限。
105
1062. 导入distributedDeviceManager模块，所有与设备管理相关的功能API，都是通过该模块提供的。
107
108   ```ts
109   import { distributedDeviceManager } from '@kit.DistributedServiceKit';
110   ```
111
1123. 导入BusinessError模块，用于获取distributedDeviceManager模块相关接口抛出的错误码。
113
114   ```ts
115   import { BusinessError } from '@kit.BasicServicesKit';
116   ```
117
1184. 创建设备管理实例，设备管理实例是分布式设备管理方法的调用入口，并注册发现设备的回调。
119
120   ```ts
121   try {
122     let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld');
123     dmInstance.on('discoverSuccess', data => console.log('discoverSuccess on:' + JSON.stringify(data)));
124     dmInstance.on('discoverFailure', data => console.log('discoverFailure on:' + JSON.stringify(data)));
125   } catch(err) {
126     let e: BusinessError = err as BusinessError;
127     console.error('createDeviceManager errCode:' + e.code + ',errMessage:' + e.message);
128   }
129   ```
130
1315. 发现周边设备。发现状态持续两分钟，超过两分钟，会停止发现，最大发现数量99个。
132
133   ```ts
134   interface DiscoverParam {
135     discoverTargetType: number;
136   }
137   interface FilterOptions {
138     availableStatus: number;
139     discoverDistance: number;
140     authenticationStatus: number;
141     authorizationType: number;
142   }
143   let discoverParam: Record<string, number> = {
144     'discoverTargetType': 1
145   };
146   let filterOptions: Record<string, number> = {
147     'availableStatus': 0
148   };
149   try {
150     dmInstance.startDiscovering(discoverParam, filterOptions);
151   } catch (err) {
152     let e: BusinessError = err as BusinessError;
153     console.error('startDiscovering errCode:' + e.code + ',errMessage:' + e.message);
154   }
155   ```
156
157## 设备绑定开发指导
158
159### 场景概述
160
161开发者发现周边不可信设备后，通过绑定接口建立可信关系。
162
163### 接口说明
164
165bindTarget(deviceId: string, bindParam: {[key:&nbsp;string]:&nbsp;Object;} , callback: AsyncCallback&lt;{deviceId: string;}>): void;
166
167设备绑定。详细信息参见：[bindTarget](../reference/apis-distributedservice-kit/js-apis-distributedDeviceManager.md#bindtarget)。
168
169### 开发步骤
170
1711. 申请分布式数据同步权限。
172
1732. 发现周边不可信设备。
174
1753. 选择不可信设备id，发起设备绑定。
176
177   ```ts
178   class Data {
179     deviceId: string = '';
180   }
181   let deviceId = 'XXXXXXXX';
182   let bindParam: Record<string, string | number> = {
183     'bindType': 1,
184     'targetPkgName': 'xxxx',
185     'appName': 'xxxx',
186     'appOperation': 'xxxx',
187     'customDescription': 'xxxx'
188   };
189   try {
190     dmInstance.bindTarget(deviceId, bindParam, (err: BusinessError, data: Data) => {
191       if (err) {
192         console.error('bindTarget errCode:' + err.code + ',errMessage:' + err.message);
193         return;
194       }
195       console.info('bindTarget result:' + JSON.stringify(data));
196     });
197   } catch (err) {
198     let e: BusinessError = err as BusinessError;
199     console.error('bindTarget errCode:' + e.code + ',errMessage:' + e.message);
200   }
201   ```
202
203## 设备信息查询开发指导
204
205### 场景概述
206
207设备与周边设备建立可信关系后，通过设备信息查询接口可以获取所有上线并且可信的设备。
208
209### 接口说明
210
211getAvailableDeviceListSync(): Array&lt;DeviceBasicInfo&gt;;
212
213设备信息查询。详细信息参见：[getAvailableDeviceListSync](../reference/apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)。
214
215### 开发步骤
216
2171. 申请分布式数据同步权限。
218
2192. 发现周边不可信设备。
220
2213. 建立设备间的可信关系。
222
2234. 查询周围上线并且可信的设备。
224
225   ```ts
226   try {
227     let deviceInfoList: Array<distributedDeviceManager.DeviceBasicInfo> = dmInstance.getAvailableDeviceListSync();
228   } catch (err) {
229     let e: BusinessError = err as BusinessError;
230     console.error('getAvailableDeviceListSync errCode:' + e.code + ',errMessage:' + e.message);
231   }
232   ```
233
234## 设备上下线监听开发指导
235
236### 场景概述
237
238周边可信设备可用后会给业务报上线通知，当设备不可用时会给业务报下线通知。
239
240### 接口说明
241
242on(type: 'deviceStateChange', callback: Callback&lt;{ action: DeviceStateChange; device: DeviceBasicInfo; }&gt;): void;
243
244设备上下线监听。详细信息参见：[on('deviceStateChange')](../reference/apis-distributedservice-kit/js-apis-distributedDeviceManager.md#ondevicestatechange)。
245
246### 开发步骤
247
2481. 申请分布式数据同步权限。
249
2502. 导入distributedDeviceManager模块，所有与设备管理相关的功能API，都是通过该模块提供的。
251
252   ```ts
253   import { distributedDeviceManager } from '@kit.DistributedServiceKit';
254   ```
255
2563. 导入BusinessError模块，用于获取distributedDeviceManager模块相关接口抛出的错误码。
257
258   ```ts
259   import { BusinessError } from '@kit.BasicServicesKit';
260   ```
261
2624. 创建设备管理实例，设备管理实例是分布式设备管理方法的调用入口，并注册设备上下线回调。
263
264   ```ts
265   try {
266     let dmInstance = distributedDeviceManager.createDeviceManager('ohos.samples.jsHelloWorld');
267     dmInstance.on('deviceStateChange', data => console.log('deviceStateChange on:' + JSON.stringify(data)));
268   } catch(err) {
269     let e: BusinessError = err as BusinessError;
270     console.error('createDeviceManager errCode:' + e.code + ',errMessage:' + e.message);
271   }
272   ```
273