1# **DeviceManager**
2
3## Introduction
4
5DeviceManager supports authentication and networking for account-independent distributed devices. It provides a set of APIs for listening, discovery, and authentication of distributed devices.
6
7The figure below shows the architecture and dependencies of DeviceManager:
8
9![](figures/devicemanager_en.png)
10
11## Directory Structure
12
13```
14foundation/distributedhardware/device_manager
15├── common                        # Header files of common capabilities
16│   └── include
17│       └── ipc
18│           └── model             # Header files of the IPC function module
19├── display                       # Display HAP code
20│   └── entry
21│       └── src
22│           └── main
23│               ├── js            # JS code for the PIN display ServiceExtensionAbility
24│               └── resources     # Resource configuration files for PIN display ServiceExtensionAbility
25├── figures
26├── interfaces
27│   ├── inner_kits                # Internal interfaces and their implementation
28│   │   └── native_cpp            # Internal native interfaces and their implementation
29│   │       ├── include
30│   │       │   ├── ipc           # IPC header files
31│   │       │   │   ├── lite      # Small system
32│   │       │   │   └── standard  # Standard system
33│   │       │   └── notify        # IPC callback header files
34│   │       └── src
35│   │           ├── ipc           # IPC core code
36│   │           │   ├── lite      # Small system
37│   │           │   └── standard  # Standard system
38│   │           └── notify         IPC callback core code
39│   └── kits                      # External interfaces and their implementation
40│       └── js                    # External JS interfaces and their implementation
41│           ├── include           # External JS interfaces and their implementation files
42│           └── src               # External JS interface and their implementation code
43├── sa_profile
44├── services
45│   └── devicemanagerservice      # devicemanagerservice core code
46│       ├── include
47│       │   ├── ability           # Header files related to PIN display ServiceExtensionAbility startup management
48│       │   ├── auth              # Header files related to device authentication
49│       │   ├── ipc               # IPC header files
50│       │   │   ├── lite          # Small system
51│       │   │   └── standard      # Standard system
52│       │   ├── message           # Header files related to message parsing
53│       │   ├── requestauth       # Header files related to device authentication
54│       │   ├── softbus           # Header files related to DSoftBus
55│       │   └── timer             # Header files related to timer processing
56│       └── src
57│           ├── ability           # Core code related to PIN display ServiceExtensionAbility startup management
58│           │   ├── lite          # Small system
59│           │   └── standard      # Standard system
60│           ├── auth              # Core code related to device authentication
61│           ├── ipc               # IPC core code
62│           │   ├── lite          # Small system
63│           │   └── standard      # Standard system
64│           ├── message           # Core code for message parsing
65│           ├── requestauth       # Core code for device authentication
66│           ├── softbus           # Core code for DSoftBus
67│           └── timer             # Core code for timer processing
68└── utils                         # Header files of utils
69    ├── include
70    │   ├── cipher                # Header files related to encryption and decryption
71    │   ├── ipc                   # IPC common header files
72    │   │   ├── lite              # Small system
73    │   │   └── standard          # Standard system
74    │   └── log                   # Log-related header files
75    └── src
76        ├── cipher                # Core code of encryption and decryption
77        ├── ipc                   # IPC common core code
78        │   ├── lite              # Small system
79        │   └── standard          # Standard system
80        └── log                   # Log-related core code
81```
82
83## Constraints
84
85- Programming languages: JS and C++
86- Applicable devices: OpenHarmony devices such as the Hi3516D V300 development board
87
88
89## Available APIs
90
91Currently, DeviceManager does not support permission management. Its system APIs can be called only by system applications. In later versions, strict permission control will be implemented.
92For details about the APIs, see *ohos.distributedHardware.deviceManager.d.ts* in [**interface_sdk-js repository**](https://gitee.com/openharmony/interface_sdk-js/).
93
94- Public APIs
95
96  Before using APIs in **DeviceManager**, call **createDeviceManager** to create a **DeviceManager** instance.
97
98  If you no longer need to use the APIs, release the **DeviceManager** instance.
99
100| Prototype                                                        | Description                           |
101| ------------------------------------------------------------ | ------------------------------- |
102| createDeviceManager(bundleName: string, callback: AsyncCallback<DeviceManager>): void; | Obtains a **DeviceManager** instance in asynchronous mode.|
103| release(): void;                                             | Releases a **DeviceManager** instance.          |
104
105
106- System APIs
107
108  DeviceManager provides APIs related to trusted device list obtaining, device state listening, device discovery, and device authentication. These APIs are system APIs and can be invoked only by system applications.
109
110  The APIs for starting and stopping device discovery must be used in pairs, with the same subscribe ID.
111
112| Prototype                                                        | Description                |
113| ------------------------------------------------------------ | -------------------- |
114| getTrustedDeviceListSync(): Array<DeviceInfo>;                                                                                            | Obtains the trusted device list.|
115| on(type: 'deviceStateChange', callback: Callback<{ action: DeviceStateChangeAction, device: DeviceInfo }>): void;                         | Subscribes to device state changes.|
116| off(type: 'deviceStateChange', callback?: Callback<{ action: DeviceStateChangeAction, device: DeviceInfo }>): void;                       | Unsubscribes from device state changes.|
117| on(type: 'serviceDie', callback: () => void): void;                                                                                       | Subscribes to device errors.|
118| off(type: 'serviceDie', callback?: () => void): void;                                                                                     | Unsubscribes from service errors.|
119| startDeviceDiscovery(subscribeInfo: SubscribeInfo): void;    | Starts device discovery.        |
120| stopDeviceDiscovery(subscribeId: number): void;              | Stops device discovery.        |
121| authenticateDevice(deviceInfo: DeviceInfo, authparam: AuthParam, callback: AsyncCallback<{deviceId: string, pinTone ?: number}>): void; | Authenticates a device.        |
122| setUserOperation(operateAction: number, params: string): void;    | Set user ui operation behavior         |
123| verifyAuthInfo(authInfo: AuthInfo, callback: AsyncCallback<{deviceId: string, level: number}>): void; | Verifies device authentication information.    |
124| on(type: 'deviceFound', callback: Callback<{ subscribeId: number, device: DeviceInfo }>): void; | Subscribes to discovered device list changes.    |
125| off(type: 'deviceFound', callback?: Callback<{ subscribeId: number, device: DeviceInfo }>): void; | Unsubscribes from discovered device list changes.|
126| on(type: 'discoverFail', callback: Callback<{ subscribeId: number, reason: number }>): void; | Subscribes to device discovery failures.    |
127| off(type: 'discoverFail', callback?: Callback<{ subscribeId: number, reason: number }>): void; | Unsubscribes from device discovery failures.|
128| on(type: 'publishSuccess', callback: Callback<{ publishId: number }>): void; | publish device success     |
129| off(type: 'publishSuccess', callback?: Callback<{ publishId: number }>): void; | delete unpublish device success |
130| on(type: 'publishFail', callback: Callback<{ publishId: number, reason: number }>): void; | publish device fail     |
131| off(type: 'publishFail', callback?: Callback<{ publishId: number, reason: number }>): void; | delete unpublish device fail |
132| on(type: 'uiStateChange', callback: Callback<{ param: string}>): void; | UI status change callback     |
133| off(type: 'uiStateChange', callback?: Callback<{ param: string}>): void; | Cancel UI status change callback     |
134## Sample Code
135
136```
137// Create a DeviceManager instance.
138deviceManager.createDeviceManager('com.ohos.xxxx', (err, dm) => {
139    this.log("createDeviceManager err:" + JSON.stringify(err) + '  --success:' + JSON.stringify(dm))
140    if (err) return;
141    dmClass = dm;
142    dmClass.on('serviceDie', data => this.log("serviceDie on:" + JSON.stringify(data)))
143});
144
145// Subscribe to/Unsubscribe from device state changes.
146dmClass.on('deviceStateChange', (data) => {
147    this.log("deviceStateChange on:" + JSON.stringify(data));
148    switch (data.action) {
149      case ONLINE:
150        // the device is physically online
151        break;
152      case READY:
153        // the information between devices has been synchronized in the Distributed Data Service (DDS) module,
154        // and the device is ready for running distributed services
155        break;
156      case OFFLINE:
157        // the device is physically offline
158        break;
159      case CHANGE:
160        // the device information is changed
161        break;
162      default:
163        break;
164    }
165});
166dmClass.off('deviceStateChange')
167
168// Query the trusted device list.
169var array = dmClass.getTrustedDeviceListSync();
170
171// Obtain the local device information.
172var localDeviceInfo = dmClass.getLocalDeviceInfoSync();
173
174// Start device discovery (to discover peripheral untrusted devices).
175var subscribeId = 0;
176dmClass.on('deviceFound', (data) => {
177    if (data == null) {
178        this.log("deviceFound error data=null")
179        return;
180    }
181    this.logList.push("deviceFound:" + JSON.stringify(data));
182});
183dmClass.on('discoverFail', (data) => {
184    this.log("discoverFail on:" + JSON.stringify(data));
185});
186subscribeId = Math.floor(Math.random() * 10000 + 1000)
187var info = {
188    "subscribeId": subscribeId,
189    "mode": 0xAA,
190    "medium": 0,
191    "freq": 2,
192    "isSameAccount": false,
193    "isWakeRemote": true,
194    "capability": 0
195};
196var filterOptions = {
197    "filter_op": "OR", // optional, "OR" default
198    "filters": [
199        {
200            "type": "range",
201            "value": 50 // need to filter the distance of dicovered device, in centimeters(cm).
202        }
203    ]
204};
205dmClass.startDeviceDiscovery(info, JSON.stringify(filterOptions));
206
207// Stop device discovery (used with startDeviceDiscovery).
208dmClass.stopDeviceDiscovery(subscribeId);
209
210// publish device discovery
211var publishId = 0;
212dmClass.on('publishSuccess', (data) => {
213    if (data == null) {
214        this.log("publishSuccess error data=null")
215        return;
216    }
217    this.logList.push("publishSuccess:" + JSON.stringify(data));
218});
219dmClass.on('publishFailed', (data) => {
220    this.log("publishFailed on:" + JSON.stringify(data));
221});
222publishId = Math.floor(Math.random() * 10000 + 1000)
223var info = {
224    "publishId": publishId,
225    "mode": 0xAA,
226    "freq": 2,
227    "ranging": 1
228};
229dmClass.publishDeviceDiscovery(info);
230
231// unPublish device discovery(used with publishDeviceDiscovery).
232dmClass.unPublishDeviceDiscovery(publishId);
233
234// operateAction User Operation Actions.
235/*  operateAction = 0 - allow authentication
236    operateAction = 1 - cancel authentication
237    operateAction = 2 - user operation timeout for authentication confirm
238    operateAction = 3 - cancel pincode display
239    operateAction = 4 - cancel pincode input
240    operateAction = 5 - confirm pincode input
241*/
242dmClass.setUserOperation(operation, "extra")
243dmClass.on('uiStateChange', (data) => {
244    console.log("uiStateChange executed, dialog closed" + JSON.stringify(data))
245    var tmpStr = JSON.parse(data.param)
246    this.isShow = tmpStr.verifyFailed
247    console.log("uiStateChange executed, dialog closed" + this.isShow)
248    if (!this.isShow) {
249        this.destruction()
250    }
251});
252dmClass.off('uiStateChange')
253
254// Authenticate a device.
255var deviceInfo ={
256    "deviceId": "XXXXXXXX",
257    "deviceName": "",
258    deviceType: 0
259};
260let extraInfo = {
261    "appOperation": "xxxxxxxx", // App operation. Support for user customization.
262    "customDescription": "xxxxxxxx", // Custom description. Support for user customization.
263}
264let authParam = {
265    "authType": 1,
266    "extraInfo": extraInfo
267}
268dmClass.authenticateDevice(this.deviceInfo, authParam, (err, data) => {
269    if (err) {
270        this.logList.push("authenticateDevice err:" + JSON.stringify(err));
271        console.info(TAG + "authenticateDevice err:" + JSON.stringify(err));
272        return;
273    }
274    this.logList.push("authenticateDevice result:" + JSON.stringify(data));
275    console.info(TAG + "authenticateDevice result:" + JSON.stringify(data));
276    token = data.pinToken;
277});
278
279// Cancel device authentication.
280dmClass.unAuthenticateDevice(this.deviceInfo);
281```
282## System Dialog Box ServiceExtensionAbility
283
284Only PIN authentication is supported in the current version. To support PIN authentication, an authorization prompt page, a PIN display page, and a PIN input page must be provided.
285
286Currently, the system does not support the dialog box display through the native layer. Therefore, a temporary ServiceExtensionAbility is used to display a dialog box.
287
288This ServiceExtensionAbility is called **DeviceManager_UI.hap**, which is preset as a system application.
289
290- Compilation and running
291
292  Import the **device_manager/display** project to DevEco Studio 2.2 Beta1. Copy the **@ohos.distributedHardware.deviceManager.d.ts** file in the **display** directory to the **Sdk\js\2.2.0.1\api\common** directory for compilation, building, and debugging.
293
294- Compilation environment: IDE 2.2 SDK6
295
296- Storage location of **DeviceManager_UI.hap** demo: [device_manager repository](https://gitee.com/openharmony/distributedhardware_device_manager/tree/master/display)
297
298- UI display
299
300  When DeviceManager functions as the authenticated party, the authorization prompt page and PIN display page are controlled by the **DeviceManager_UI.hap** ServiceExtensionAbility by default.
301
302  When DeviceManager functions as the authentication initiator, the PIN input page can be displayed either by **DeviceManager_UI.hap** ServiceExtensionAbility or a developer-customized page. To customize the PIN input page, set the **displayOwner** parameter in the **extraInfo** attribute of the **AuthParam** parameter of the **authenticateDevice** API to **1**.
303
304### Repositories Involved
305****
306
307[**interface_sdk-js**](https://gitee.com/openharmony/interface_sdk-js/)
308
309[**applications_hap**](https://gitee.com/openharmony/applications_hap)
310
311**device_manager**
312