1# @ohos.enterprise.deviceSettings (Device Settings Management) 2 3The **deviceSettings** module provides APIs for setting enterprise devices, including obtaining the screen-off time of a device. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9> - The APIs of this module can be used only in the stage model. 10> 11> - The APIs provided by this module can be called only by a [device administrator application](enterpriseDeviceManagement-overview.md#basic-concepts) that is [enabled](js-apis-enterprise-adminManager.md#adminmanagerenableadmin). 12 13## Modules to Import 14 15```ts 16import deviceSettings from '@ohos.enterprise.deviceSettings'; 17``` 18 19## deviceSettings.getScreenOffTime 20 21getScreenOffTime(admin: Want, callback: AsyncCallback<number>): void 22 23Obtains the device screen-off time through the specified device administrator application. This API uses an asynchronous callback to return the result. 24 25**Required permissions**: ohos.permission.ENTERPRISE_GET_SETTINGS 26 27**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 28 29**System API**: This is a system API. 30 31**Parameters** 32 33| Name | Type | Mandatory | Description | 34| -------- | ---------------------------------------- | ---- | ------------------------------- | 35| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | 36| callback | AsyncCallback<number> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null** and **data** is the device screen-off time obtained. Otherwise, **err** is an error object. | 37 38**Error codes** 39 40For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). 41 42| ID| Error Message | 43| ------- | ---------------------------------------------------------------------------- | 44| 9200001 | the application is not an administrator of the device. | 45| 9200002 | the administrator application does not have permission to manage the device. | 46 47**Example** 48 49```ts 50import Want from '@ohos.app.ability.Want'; 51let wantTemp: Want = { 52 bundleName: 'com.example.myapplication', 53 abilityName: 'EntryAbility', 54}; 55 56deviceSettings.getScreenOffTime(wantTemp, (err, result) => { 57 if (err) { 58 console.error(`Failed to get screen off time. Code: ${err.code}, message: ${err.message}`); 59 return; 60 } 61 console.info(`Succeeded in getting screen off time, result : ${result}`); 62}); 63``` 64 65## deviceSettings.getScreenOffTime 66 67getScreenOffTime(admin: Want): Promise<number> 68 69Obtains the device screen-off time through the specified device administrator application. This API uses a promise to return the result. 70 71**Required permissions**: ohos.permission.ENTERPRISE_GET_SETTINGS 72 73**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 74 75**System API**: This is a system API. 76 77**Parameters** 78 79| Name | Type | Mandatory | Description | 80| ----- | ----------------------------------- | ---- | ------- | 81| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| 82 83**Return value** 84 85| Type | Description | 86| --------------------- | ------------------------- | 87| Promise<number> | Promise used to return the device screen-off time. | 88 89**Error codes** 90 91For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). 92 93| ID| Error Message | 94| ------- | ---------------------------------------------------------------------------- | 95| 9200001 | the application is not an administrator of the device. | 96| 9200002 | the administrator application does not have permission to manage the device. | 97 98**Example** 99 100```ts 101import Want from '@ohos.app.ability.Want'; 102import { BusinessError } from '@ohos.base'; 103let wantTemp: Want = { 104 bundleName: 'com.example.myapplication', 105 abilityName: 'EntryAbility', 106}; 107 108deviceSettings.getScreenOffTime(wantTemp).then((result) => { 109 console.info(`Succeeded in getting screen off time, result : ${result}`); 110}).catch((err: BusinessError) => { 111 console.error(`Failed to get screen off time. Code: ${err.code}, message: ${err.message}`); 112}); 113``` 114 115## deviceSettings.installUserCertificate 116 117installUserCertificate(admin: Want, certificate: CertBlob, callback: AsyncCallback<string>): void 118 119Installs a user certificate through the specified device administrator application. This API uses an asynchronous callback to return the result. 120 121**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 122 123**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 124 125**System API**: This is a system API. 126 127**Parameters** 128 129| Name | Type | Mandatory | Description | 130| -------- | ---------------------------------------- | ---- | ------------------------------- | 131| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | 132| certificate | [CertBlob](#certblob) | Yes | Information about the certificate to install. | 133| callback | AsyncCallback<string> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | 134 135**Error codes** 136 137For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). 138 139| ID| Error Message | 140| ------- | ---------------------------------------------------------------------------- | 141| 9200001 | the application is not an administrator of the device. | 142| 9200002 | the administrator application does not have permission to manage the device. | 143| 9201001 | manage certificate failed | 144 145**Example** 146 147```ts 148import Want from '@ohos.app.ability.Want'; 149import { BusinessError } from '@ohos.base'; 150let wantTemp: Want = { 151 bundleName: 'com.example.myapplication', 152 abilityName: 'EntryAbility', 153}; 154let certFileArray: Uint8Array = new Uint8Array(); 155// The variable context needs to be initialized in MainAbility's onCreate callback function 156// test.cer needs to be placed in the rawfile directory 157getContext().resourceManager.getRawFileContent("test.cer").then((value) => { 158 certFileArray = value; 159 deviceSettings.installUserCertificate(wantTemp, { inData: certFileArray, alias: "cert_alias_xts" }, (err, result) => { 160 if (err) { 161 console.error(`Failed to install user certificate. Code: ${err.code}, message: ${err.message}`); 162 } else { 163 console.info(`Succeeded in installing user certificate, result : ${JSON.stringify(result)}`); 164 } 165 }); 166}).catch((error: BusinessError) => { 167 console.error(`Failed to get row file content. message: ${error.message}`); 168 return 169}); 170``` 171 172## deviceSettings.installUserCertificate 173 174installUserCertificate(admin: Want, certificate: CertBlob): Promise<string> 175 176Installs a user certificate through the specified device administrator application. This API uses a promise to return the result. 177 178**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 179 180**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 181 182**System API**: This is a system API. 183 184**Parameters** 185 186| Name | Type | Mandatory | Description | 187| ----- | ----------------------------------- | ---- | ------- | 188| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| 189| certificate | [CertBlob](#certblob) | Yes | Information about the certificate to install. | 190 191**Return value** 192 193| Type | Description | 194| --------------------- | ------------------------- | 195| Promise<string> | Promise used to return the URI of the installed certificate. This URI can be used to uninstall the certificate.| 196 197**Error codes** 198 199For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). 200 201| ID| Error Message | 202| ------- | ---------------------------------------------------------------------------- | 203| 9200001 | the application is not an administrator of the device. | 204| 9200002 | the administrator application does not have permission to manage the device. | 205| 9201001 | manage certificate failed | 206 207**Example** 208 209```ts 210import Want from '@ohos.app.ability.Want'; 211import { BusinessError } from '@ohos.base'; 212let wantTemp: Want = { 213 bundleName: 'com.example.myapplication', 214 abilityName: 'EntryAbility', 215}; 216let certFileArray: Uint8Array = new Uint8Array(); 217// The variable context needs to be initialized in MainAbility's onCreate callback function 218// test.cer needs to be placed in the rawfile directory 219getContext().resourceManager.getRawFileContent("test.cer").then((value) => { 220 certFileArray = value 221 deviceSettings.installUserCertificate(wantTemp, { inData: certFileArray, alias: "cert_alias_xts" }) 222 .then((result) => { 223 console.info(`Succeeded in installing user certificate, result : ${JSON.stringify(result)}`); 224 }).catch((err: BusinessError) => { 225 console.error(`Failed to install user certificate. Code: ${err.code}, message: ${err.message}`); 226 }) 227}).catch((error: BusinessError) => { 228 console.error(`Failed to get row file content. message: ${error.message}`); 229 return 230}); 231``` 232 233## CertBlob 234 235Represents the certificate information. 236 237**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 238 239**System API**: This is a system API. 240 241| Name | Type | Mandatory| Description | 242| ----------- | --------| ----- | ------------------------------- | 243| inData | Uint8Array | Yes| Binary content of the certificate.| 244| alias | string | Yes| Certificate alias.| 245 246## deviceSettings.uninstallUserCertificate 247 248uninstallUserCertificate(admin: Want, certUri: string, callback: AsyncCallback<void>): void 249 250Uninstalls a user certificate through the specified device administrator application. This API uses an asynchronous callback to return the result. 251 252**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 253 254**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 255 256**System API**: This is a system API. 257 258**Parameters** 259 260| Name | Type | Mandatory | Description | 261| -------- | ---------------------------------------- | ---- | ------------------------------- | 262| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | 263| certUri | string | Yes | Certificate URI, which is returned by **installUserCertificate()**. | 264| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | 265 266**Error codes** 267 268For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). 269 270| ID| Error Message | 271| ------- | ---------------------------------------------------------------------------- | 272| 9200001 | the application is not an administrator of the device. | 273| 9200002 | the administrator application does not have permission to manage the device. | 274| 9201001 | manage certificate failed | 275 276**Example** 277 278```ts 279import Want from '@ohos.app.ability.Want'; 280let wantTemp: Want = { 281 bundleName: 'com.example.myapplication', 282 abilityName: 'EntryAbility', 283}; 284let aliasStr = "certName" 285deviceSettings.uninstallUserCertificate(wantTemp, aliasStr, (err) => { 286 if (err) { 287 console.error(`Failed to uninstall user certificate. Code: ${err.code}, message: ${err.message}`); 288 return; 289 } 290 console.info(`Succeeded in uninstalling user certificate`); 291}); 292``` 293 294## deviceSettings.uninstallUserCertificate 295 296uninstallUserCertificate(admin: Want, certUri: string): Promise<void> 297 298Uninstalls a user certificate through the specified device administrator application. This API uses a promise to return the result. 299 300**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 301 302**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 303 304**System API**: This is a system API. 305 306**Parameters** 307 308| Name | Type | Mandatory | Description | 309| ----- | ----------------------------------- | ---- | ------- | 310| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| 311| certUri | string | Yes | Certificate URI, which is returned by **installUserCertificate()**. | 312 313**Return value** 314 315| Type | Description | 316| --------------------- | ------------------------- | 317| Promise<void> | Promise that returns no value. An error object will be thrown if the operation fails.| 318 319**Error codes** 320 321For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). 322 323| ID| Error Message | 324| ------- | ---------------------------------------------------------------------------- | 325| 9200001 | the application is not an administrator of the device. | 326| 9200002 | the administrator application does not have permission to manage the device. | 327| 9201001 | manage certificate failed | 328 329**Example** 330 331```ts 332import Want from '@ohos.app.ability.Want'; 333import { BusinessError } from '@ohos.base'; 334let wantTemp: Want = { 335 bundleName: 'com.example.myapplication', 336 abilityName: 'EntryAbility', 337}; 338let aliasStr = "certName" 339deviceSettings.uninstallUserCertificate(wantTemp, aliasStr).then(() => { 340 console.info(`Succeeded in uninstalling user certificate`); 341}).catch((err: BusinessError) => { 342 console.error(`Failed to uninstall user certificate. Code is ${err.code}, message is ${err.message}`); 343}); 344``` 345