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