1/* 2 * Copyright (c) 2023-2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit MDMKit 19 */ 20 21import type { AsyncCallback } from './@ohos.base'; 22import type Want from './@ohos.app.ability.Want'; 23 24/** 25 * This module provides the capability to manage the device settings of the enterprise devices. 26 * 27 * @namespace deviceSettings 28 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 29 * @since 10 30 */ 31declare namespace deviceSettings { 32 /** 33 * Device power policy. 34 * 35 * @typedef PowerPolicy 36 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 37 * @systemapi 38 * @stagemodelonly 39 * @since 11 40 */ 41 export interface PowerPolicy { 42 /** 43 * An action that needs to be performed after a certain delay 44 * 45 * @type { PowerPolicyAction } 46 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 47 * @systemapi 48 * @stagemodelonly 49 * @since 11 50 */ 51 powerPolicyAction: PowerPolicyAction; 52 53 /** 54 * Delay time fo execute power policy action 55 * 56 * @type { number } 57 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 58 * @systemapi 59 * @stagemodelonly 60 * @since 11 61 */ 62 delayTime: number; 63 } 64 65 /** 66 * Actions of power policy. 67 * 68 * @enum { number } 69 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 70 * @systemapi 71 * @since 11 72 */ 73 enum PowerPolicyAction { 74 /** 75 * Performs no action after a certain delay 76 * 77 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 78 * @systemapi 79 * @stagemodelonly 80 * @since 11 81 */ 82 NONE = 0, 83 84 /** 85 * Performs auto suspend action after a certain delay 86 * 87 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 88 * @systemapi 89 * @stagemodelonly 90 * @since 11 91 */ 92 AUTO_SUSPEND, 93 94 /** 95 * Performs force suspend action after a certain delay 96 * 97 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 98 * @systemapi 99 * @stagemodelonly 100 * @since 11 101 */ 102 FORCE_SUSPEND, 103 104 /** 105 * Performs hibernate action after a certain delay 106 * 107 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 108 * @systemapi 109 * @stagemodelonly 110 * @since 11 111 */ 112 HIBERNATE, 113 114 /** 115 * Performs shutdown action after a certain delay 116 * 117 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 118 * @systemapi 119 * @stagemodelonly 120 * @since 11 121 */ 122 SHUTDOWN 123 } 124 125 /** 126 * The scene to execute power policy. 127 * 128 * @enum { number } 129 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 130 * @systemapi 131 * @since 11 132 */ 133 enum PowerScene { 134 /** 135 * Time out scene 136 * 137 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 138 * @systemapi 139 * @stagemodelonly 140 * @since 11 141 */ 142 TIME_OUT = 0 143 } 144 145 /** 146 * User certificate data. 147 * 148 * @typedef CertBlob 149 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 150 * @systemapi 151 * @stagemodelonly 152 * @since 10 153 */ 154 export interface CertBlob { 155 /** 156 * The certificate content 157 * 158 * @type { Uint8Array } 159 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 160 * @systemapi 161 * @stagemodelonly 162 * @since 10 163 */ 164 inData: Uint8Array; 165 166 /** 167 * The certificate alias 168 * 169 * @type { string } 170 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 171 * @systemapi 172 * @stagemodelonly 173 * @since 10 174 */ 175 alias: string; 176 } 177 178 /** 179 * Sets the screen off time. 180 * This function can be called by a super administrator. 181 * 182 * @permission ohos.permission.ENTERPRISE_SET_SCREENOFF_TIME 183 * @param { Want } admin - admin indicates the enterprise admin extension ability information. 184 * The admin must have the corresponding permission. 185 * @param { number } time - screen off time. The minimum value is 15000. It is recommended that the time 186 * is consistent with the optional screen-off time of the device. 187 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 188 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 189 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 190 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 191 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 192 * 2. Incorrect parameter types; 3. Parameter verification failed. 193 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 194 * @systemapi 195 * @stagemodelonly 196 * @since 11 197 */ 198 function setScreenOffTime(admin: Want, time: number): void; 199 200 /** 201 * Gets the device screen off time. 202 * This function can be called by a super administrator. 203 * 204 * @permission ohos.permission.ENTERPRISE_GET_SETTINGS 205 * @param { Want } admin - admin indicates the enterprise admin extension ability information. 206 * The admin must have the corresponding permission. 207 * @param { AsyncCallback<number> } callback - the callback of getScreenOffTime. 208 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 209 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 210 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 211 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 212 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 213 * 2. Incorrect parameter types; 3. Parameter verification failed. 214 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 215 * @systemapi 216 * @StageModelOnly 217 * @since 10 218 */ 219 function getScreenOffTime(admin: Want, callback: AsyncCallback<number>): void; 220 221 /** 222 * Gets the device screen off time. 223 * This function can be called by a super administrator. 224 * 225 * @permission ohos.permission.ENTERPRISE_GET_SETTINGS 226 * @param { Want } admin - admin indicates the enterprise admin extension ability information. 227 * The admin must have the corresponding permission. 228 * @returns { Promise<number> } the promise returned by the getScreenOffTime. 229 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 230 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 231 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 232 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 233 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 234 * 2. Incorrect parameter types; 3. Parameter verification failed. 235 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 236 * @systemapi 237 * @StageModelOnly 238 * @since 10 239 */ 240 function getScreenOffTime(admin: Want): Promise<number>; 241 242 /** 243 * Install user certificate. 244 * This function can be called by a super administrator. 245 * 246 * @permission ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 247 * @param { Want } admin - admin indicates the enterprise admin extension ability information. 248 * The admin must have the corresponding permission. 249 * @param { CertBlob } certificate - certificate file content and alias. It cannot be empty or more than 40 characters. 250 * @param { AsyncCallback<string> } callback - The callback carries the uri of the certificate used to uninstall 251 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 252 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 253 * @throws { BusinessError } 9201001 - Failed to manage the certificate. 254 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 255 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 256 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 257 * 2. Incorrect parameter types; 3. Parameter verification failed. 258 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 259 * @systemapi 260 * @stagemodelonly 261 * @since 10 262 */ 263 function installUserCertificate(admin: Want, certificate: CertBlob, callback: AsyncCallback<string>): void; 264 265 /** 266 * Install user certificate. 267 * This function can be called by a super administrator. 268 * 269 * @permission ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 270 * @param { Want } admin - admin indicates the enterprise admin extension ability information. 271 * The admin must have the corresponding permission. 272 * @param { CertBlob } certificate - certificate file content and alias. It cannot be empty or more than 40 characters. 273 * @returns { Promise<string> } the promise carries the uri of the certificate used to uninstall 274 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 275 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 276 * @throws { BusinessError } 9201001 - Failed to manage the certificate. 277 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 278 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 279 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 280 * 2. Incorrect parameter types; 3. Parameter verification failed. 281 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 282 * @systemapi 283 * @stagemodelonly 284 * @since 10 285 */ 286 function installUserCertificate(admin: Want, certificate: CertBlob): Promise<string>; 287 288 /** 289 * Uninstall user certificate. 290 * This function can be called by a super administrator. 291 * 292 * @permission ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 293 * @param { Want } admin - admin indicates the enterprise admin extension ability information. 294 * The admin must have the corresponding permission. 295 * @param { string } certUri - uri of the certificate. It cannot be empty or more than 64 characters. 296 * @param { AsyncCallback<void> } callback - the callback of uninstallUserCertificate. 297 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 298 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 299 * @throws { BusinessError } 9201001 - Failed to manage the certificate. 300 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 301 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 302 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 303 * 2. Incorrect parameter types; 3. Parameter verification failed. 304 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 305 * @systemapi 306 * @stagemodelonly 307 * @since 10 308 */ 309 function uninstallUserCertificate(admin: Want, certUri: string, callback: AsyncCallback<void>): void; 310 311 /** 312 * Uninstall user certificate. 313 * This function can be called by a super administrator. 314 * 315 * @permission ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE 316 * @param { Want } admin - admin indicates the enterprise admin extension ability information. 317 * The admin must have the corresponding permission. 318 * @param { string } certUri - uri of the certificate. It cannot be empty or more than 64 characters. 319 * @returns { Promise<void> } the promise returned by the uninstallUserCertificate. 320 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 321 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 322 * @throws { BusinessError } 9201001 - Failed to manage the certificate. 323 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 324 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 325 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 326 * 2. Incorrect parameter types; 3. Parameter verification failed. 327 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 328 * @systemapi 329 * @stagemodelonly 330 * @since 10 331 */ 332 function uninstallUserCertificate(admin: Want, certUri: string): Promise<void>; 333 334 /** 335 * Sets the power policy. 336 * This function can be called by a super administrator. 337 * 338 * @permission ohos.permission.ENTERPRISE_MANAGE_SETTINGS 339 * @param { Want } admin - admin indicates the enterprise admin extension ability information. 340 * The admin must have the corresponding permission. 341 * @param { PowerScene } powerScene - the scene to execute power policy. Only timeout scenario is supported now. 342 * @param { PowerPolicy } powerPolicy - device power policy. 343 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 344 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 345 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 346 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 347 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 348 * 2. Incorrect parameter types; 3. Parameter verification failed. 349 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 350 * @systemapi 351 * @stagemodelonly 352 * @since 11 353 */ 354 function setPowerPolicy(admin: Want, powerScene: PowerScene, powerPolicy: PowerPolicy): void; 355 356 /** 357 * Gets the power policy. 358 * This function can be called by a super administrator. 359 * 360 * @permission ohos.permission.ENTERPRISE_MANAGE_SETTINGS 361 * @param { Want } admin - admin indicates the enterprise admin extension ability information. 362 * The admin must have the corresponding permission. 363 * @param { PowerScene } powerScene - the scene to execute power policy. Only timeout scenario is supported now. 364 * @returns { PowerPolicy } device power policy. 365 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 366 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 367 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 368 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 369 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 370 * 2. Incorrect parameter types; 3. Parameter verification failed. 371 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 372 * @systemapi 373 * @stagemodelonly 374 * @since 11 375 */ 376 function getPowerPolicy(admin: Want, powerScene: PowerScene): PowerPolicy; 377 378 /** 379 * Sets the device settings value. 380 * This function can be called by a super administrator. 381 * 382 * @permission ohos.permission.ENTERPRISE_MANAGE_SETTINGS 383 * @param { Want } admin - admin indicates the enterprise admin extension ability information. 384 * The admin must have the corresponding permission. 385 * @param { string } item - item indicates the device properties that need to be set, including screenOff, powerPolicy and dateTime. 386 * screenOff means the device screen off time, powerPolicy means the device power policy 387 * and dataTime means the device system time. 388 * @param { string } value - device settings policy. 389 * When the power policy is set, only timeout scenario is available now. 390 * When the screen off time is set, the minimum value is 15000. It is recommended that 391 * the time is consistent with the optional screen-off time of the device. 392 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 393 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 394 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 395 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 396 * 2. Incorrect parameter types; 3. Parameter verification failed. 397 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 398 * @stagemodelonly 399 * @since 12 400 */ 401 function setValue(admin: Want, item: string, value: string): void; 402 403 /** 404 * Gets the device settings value. 405 * This function can be called by a super administrator. 406 * 407 * @permission ohos.permission.ENTERPRISE_MANAGE_SETTINGS 408 * @param { Want } admin - admin indicates the enterprise admin extension ability information. 409 * The admin must have the corresponding permission. 410 * @param { string } item - item indicates the device properties that need to be get, including screenOff and powerPolicy. 411 * screenOff means the device screen off time, powerPolicy means the device power policy. 412 * @returns { string } device settings policy. 413 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 414 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 415 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 416 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 417 * 2. Incorrect parameter types; 3. Parameter verification failed. 418 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 419 * @stagemodelonly 420 * @since 12 421 */ 422 function getValue(admin: Want, item: string): string; 423 424 /** 425 * Sets home wallpaper. 426 * This function can be called by a super administrator. 427 * 428 * @permission ohos.permission.ENTERPRISE_SET_WALLPAPER 429 * @param { Want } admin - admin indicates the enterprise admin extension ability information. 430 * The admin must have the corresponding permission. 431 * @param { number } fd - the descriptor of home wallpaper file. 432 * @returns { Promise<void> } the promise returned by the setHomeWallpaper. 433 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 434 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 435 * @throws { BusinessError } 9200012 - Parameter verification failed. 436 * @throws { BusinessError } 201 - Permission verification failed.The application does not have the permission required to call the API. 437 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 438 * @stagemodelonly 439 * @since 20 440 */ 441 function setHomeWallpaper(admin: Want, fd: number): Promise<void>; 442 443 /** 444 * Sets unlock wallpaper. 445 * This function can be called by a super administrator. 446 * 447 * @permission ohos.permission.ENTERPRISE_SET_WALLPAPER 448 * @param { Want } admin - admin indicates the enterprise admin extension ability information. 449 * The admin must have the corresponding permission. 450 * @param { number } fd - the descriptor of unlock wallpaper file. 451 * @returns { Promise<void> } the promise returned by the setUnlockWallpaper. 452 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 453 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 454 * @throws { BusinessError } 9200012 - Parameter verification failed. 455 * @throws { BusinessError } 201 - Permission verification failed.The application does not have the permission required to call the API. 456 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 457 * @stagemodelonly 458 * @since 20 459 */ 460 function setUnlockWallpaper(admin: Want, fd: number): Promise<void>; 461} 462 463export default deviceSettings; 464