README_zh.md
1# **DeviceManager组件**
2
3## 简介
4
5DeviceManager组件在OpenHarmony上提供账号无关的分布式设备的认证组网能力，并为开发者提供了一套用于分布式设备间监听、发现和认证的接口。
6
7其组成及依赖如下所示：
8
9
10
11## 目录
12
13```
14foundation/distributedhardware/devicemanager
15├── common #公共能力头文件存放目录
16│ └── include
17│ └── ipc
18│ └── model #ipc功能模块头文件存放目录
19├── display #DM显示hap代码
20│ └── entry
21│ └── src
22│ └── main
23│ ├── js #DM PIN码显示FA相关JS代码
24│ └── resources #DM PIN码显示FA相关资源配置文件目录
25├── figures
26├── interfaces
27│ ├── inner_kits #内部接口及实现存放目录
28│ │ └── native_cpp #内部native接口及实现存放目录
29│ │ ├── include
30│ │ │ ├── ipc #ipc头文件存放目录
31│ │ │ │ ├── lite #L1
32│ │ │ │ └── standard #L2
33│ │ │ └── notify #ipc回调通知头文件目录
34│ │ └── src
35│ │ ├── ipc #ipc功能代码
36│ │ │ ├── lite #L1
37│ │ │ └── standard #L2
38│ │ └── notify ipc回调通知功能代码
39│ └── kits #外接口及实现存放目录
40│ └── js #外部JS接口及实现存放目录
41│ ├── include #外部JS接口及实现欧文件存放目录
42│ └── src #外部JS接口及实现代码
43├── sa_profile
44├── services
45│ └── devicemanagerservice #devicemanagerservice服务实现核心代码
46│ ├── include
47│ │ ├── ability #与PIN码显示FA拉起管理相关头文件
48│ │ ├── auth #devie_auth交互相关头文件
49│ │ ├── ipc #进程间通信相关头文件
50│ │ │ ├── lite #L1
51│ │ │ └── standard #L2
52│ │ ├── message #消息数据解析相关头文件
53│ │ ├── requestauth #设备认证功能相关头文件
54│ │ ├── softbus #软总线相关头文件
55│ │ └── timer #定时器处理相关头文件
56│ └── src
57│ ├── ability #与PIN码显示FA拉起管理相关功能代码
58│ │ ├── lite #L1
59│ │ └── standard #L2
60│ ├── auth #devie_auth交互相关核心代码
61│ ├── ipc #进程间通信相功能代码
62│ │ ├── lite #L1
63│ │ └── standard #L2
64│ ├── message #消息数据解析相功能代码
65│ ├── requestauth #设备认证功能代码
66│ ├── softbus #通道建立功能核心代码
67│ └── timer #timer处理代码
68└── utils #公共能力头文件存放目
69 ├── include
70 │ ├── cipher #加解密功能相关头文件
71 │ ├── ipc #ipc公共头文件存放目录
72 │ │ ├── lite #L1
73 │ │ └── standard #L2
74 │ └── log #log相关头文件存放目录
75 └── src
76 ├── cipher #加解密功能代码
77 ├── ipc #ipc公共功能代码
78 │ ├── lite #L1
79 │ └── standard #L2
80 └── log #log相关功能代码
81```
82
83## 约束
84
85- 开发语言：JS、C++
86- 适用于Hi3516DV300单板等OpenHarmony设备
87
88
89## 接口说明
90
91当前版本设备管理服务不具备权限管理的能力，接口中的system api仅供系统调用，后续版本会进行严格的权限管控。
92接口参见[**interface_sdk-js仓库的**](https://gitee.com/openharmony/interface_sdk-js/) *ohos.distributedHardware.deviceManager.d.ts*
93
94- 公共接口：
95
96 使用DeviceManager相关接口之前，需要通过createDeviceManager接口创建DeviceManager实例；
97
98 不使用DeviceManager接口的时候需要释放对应的DeviceManager实例。
99
100| 原型 | 描述 |
101| ------------------------------------------------------------ | ------------------------------- |
102| createDeviceManager(bundleName: string, callback: AsyncCallback<DeviceManager>): void; | 以异步方法获取DeviceManager实例 |
103| release(): void; | 释放DeviceManager实例 |
104
105
106
107- 开放能力接口：
108
109 提供可信设备列表获取、可信设备状态监听等接口能力，所有应用均可进行接口调用。
110
111| 原型 | 描述 |
112| ------- | ---------- |
113| getTrustedDeviceListSync(): Array<DeviceInfo>; | 获取信任设备列表 |
114| on(type: 'deviceStateChange', callback: Callback<{ action: DeviceStateChangeAction, device: DeviceInfo }>): void; | 设备状态变更回调 |
115| off(type: 'deviceStateChange', callback?: Callback<{ action: DeviceStateChangeAction, device: DeviceInfo }>): void; | 取消设备状态变更回调 |
116| on(type: 'serviceDie', callback: () => void): void; | 服务错误回调 |
117| off(type: 'serviceDie', callback?: () => void): void; | 取消服务错误回调 |
118
119
120
121- 系统能力接口：
122
123 提供周边设备发现、设备认证等相关接口，该部分作为系统能力接口，仅供系统应用调用。
124
125 开始设备发现、停止发现设备接口要配对使用，使用同一个subscribeId。
126
127| 原型 | 描述 |
128| ------------------------------------------------------------ | -------------------- |
129| startDeviceDiscovery(subscribeInfo: SubscribeInfo): void; | 开始设备发现 |
130| stopDeviceDiscovery(subscribeId: number): void; | 停止发现设备 |
131| authenticateDevice(deviceInfo: DeviceInfo, authparam: AuthParam, callback: AsyncCallback<{deviceId: string, pinTone ?: number}>): void; | 设备认证接口 |
132| verifyAuthInfo(authInfo: AuthInfo, callback: AsyncCallback<{deviceId: string, level: number}>): void; | 设备认证信息校验 |
133| on(type: 'deviceFound', callback: Callback<{ subscribeId: number, device: DeviceInfo }>): void; | 发现设备列表回调 |
134| off(type: 'deviceFound', callback?: Callback<{ subscribeId: number, device: DeviceInfo }>): void; | 取消发现设备列表回调 |
135| on(type: 'discoverFail', callback: Callback<{ subscribeId: number, reason: number }>): void; | 发现设备失败回调 |
136| off(type: 'discoverFail', callback?: Callback<{ subscribeId: number, reason: number }>): void; | 取消发现设备失败回调 |
137
138## 示例如下：
139
140```
141// 创建DeviceManager实例：
142deviceManager.createDeviceManager('com.ohos.xxxx', (err, dm) => {
143 this.log("createDeviceManager err:" + JSON.stringify(err) + ' --success:' + JSON.stringify(dm))
144 if (err) return;
145 dmClass = dm;
146 dmClass.on('serviceDie', data => this.log("serviceDie on:" + JSON.stringify(data)))
147});
148
149// 注册/去注册设备上下线监听
150dmClass.on('deviceStateChange', data => this.log("deviceStateChange on:" + JSON.stringify(data)))
151dmClass.off('deviceStateChange')
152
153// 查询可信设备列表
154var array = dmClass.getTrustedDeviceListSync();
155
156// 开始设备发现（发现周边不可信设备）
157var subscribeId = 0;
158dmClass.on('deviceFound', (data) => {
159 if (data == null) {
160 this.log("deviceFound error data=null")
161 return;
162 }
163 this.logList.push("deviceFound:" + JSON.stringify(data));
164});
165dmClass.on('discoverFail', (data) => {
166 this.log("discoverFail on:" + JSON.stringify(data));
167});
168subscribeId = Math.floor(Math.random() * 10000 + 1000)
169var info = {
170 "subscribeId": subscribeId,
171 "mode": 0xAA,
172 "medium": 0,
173 "freq": 2,
174 "isSameAccount": false,
175 "isWakeRemote": true,
176 "capability": 0
177};
178dmClass.startDeviceDiscovery(info);
179
180// 停止设备发现（需要和startDeviceDiscovery接口配对使用）
181dmClass.stopDeviceDiscovery(subscribeId);
182
183// 设备认证
184var deviceInfo ={
185 "deviceId": "XXXXXXXX",
186 "deviceName": "",
187 deviceType: 0
188}；
189let extraInfo = {
190 "targetPkgName": 'xxxxxxxx', // FA流转目标设备包名
191 "appName": "xxxxxxxx", // 对端设备应用名称
192 "appDescription": "xxxxxxxx", // app描述
193 "business": '0',
194 "displayOwner": 0
195}
196let authParam = {
197 "authType": 1,
198 "appIcon": new Uint8Array(), // app图标，可选参数，可不填
199 "appThumbnail": new Uint8Array(), // app缩略图，可选参数，可不填
200 "extraInfo": extraInfo
201}
202dmClass.authenticateDevice(this.deviceInfo, authParam, (err, data) => {
203 if (err) {
204 this.logList.push("authenticateDevice err:" + JSON.stringify(err));
205 console.info(TAG + "authenticateDevice err:" + JSON.stringify(err));
206 return;
207 }
208 this.logList.push("authenticateDevice result:" + JSON.stringify(data));
209 console.info(TAG + "authenticateDevice result:" + JSON.stringify(data));
210 token = data.pinToken;
211});
212```
213## 系统弹框FA
214
215当前版本只支持PIN码认证，需要提供PIN码认证的授权提示界面、PIN码显示界面、PIN码输入界面；
216
217当前，由于系统通过native层直接进行弹窗的能力尚不具备，这里使用一个临时的FA来进行对应界面的弹窗。
218
219该FA为：DeviceManager_UI.hap，作为系统应用进行预置。
220
221- 编译运行：
222
223 将devicemanager/display工程导入DevEco Studio 2.2 Beta1，复制display目录下的@ohos.distributedHardware.deviceManager.d.ts文件到Sdk\js\2.2.0.1\api\common目录下，进行编译构建及运行调试.
224
225 DevEco Studio使用方法请参考[DevEco Studio使用说明](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/tools_overview-0000001053582387)。
226
227- 编译环境依赖：IDE 2.2 SDK6
228
229- DeviceManager_UI.hap存放位置：[applications_hap仓库](https://gitee.com/openharmony/applications_hap)
230
231- UI显示：
232
233 DeviceManager作为认证被控端，授权提示界面、PIN码显示界面由DeviceManager_UI FA默认进行显示；
234
235 DeviceManager作为认证发起端，PIN码输入界面可以选择由DeviceManager_UI FA进行显示，还是由开发者自行显示。开发者如需自己定制PIN码输入界面，需要在authenticateDevice接口的认证参数AuthParam中，extraInfo属性里面指定displayOwner参数为1（DISPLAY_OWNER_OTHER）。
236
237### 相关仓
238****
239
240[**interface_sdk-js**](https://gitee.com/openharmony/interface_sdk-js/)
241[**applications_hap**](https://gitee.com/openharmony/applications_hap)
242**device_manager**
243
244
