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 Want from './@ohos.app.ability.Want'; 22 23/** 24 * This module provides the capability to manage the system of the enterprise devices. 25 * 26 * @namespace systemManager 27 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 28 * @stagemodelonly 29 * @since 12 30 */ 31declare namespace systemManager { 32 /** 33 * The device system update info. 34 * 35 * @typedef SystemUpdateInfo 36 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 37 * @stagemodelonly 38 * @since 12 39 */ 40 export interface SystemUpdateInfo { 41 /** 42 * The name of version need to update. 43 * 44 * @type { string } 45 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 46 * @stagemodelonly 47 * @since 12 48 */ 49 versionName: string; 50 51 /** 52 * The time when the version first received. 53 * 54 * @type { number } 55 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 56 * @stagemodelonly 57 * @since 12 58 */ 59 firstReceivedTime: number; 60 61 /** 62 * The type of version package. 63 * 64 * @type { string } 65 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 66 * @stagemodelonly 67 * @since 12 68 */ 69 packageType: string; 70 } 71 72 /** 73 * System update policy type. 74 * 75 * @enum { number } 76 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 77 * @stagemodelonly 78 * @since 12 79 */ 80 enum PolicyType { 81 /** 82 * Default update policy 83 * 84 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 85 * @stagemodelonly 86 * @since 12 87 */ 88 DEFAULT = 0, 89 90 /** 91 * Prohibit update policy 92 * 93 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 94 * @stagemodelonly 95 * @since 12 96 */ 97 PROHIBIT = 1, 98 99 /** 100 * Update to specific software version policy 101 * 102 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 103 * @stagemodelonly 104 * @since 12 105 */ 106 UPDATE_TO_SPECIFIC_VERSION = 2, 107 108 /** 109 * Update within a specified time window 110 * 111 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 112 * @stagemodelonly 113 * @since 12 114 */ 115 WINDOWS = 3, 116 117 /** 118 * Delay the update for a period of time 119 * 120 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 121 * @stagemodelonly 122 * @since 12 123 */ 124 POSTPONE = 4 125 } 126 127 /** 128 * OTA update policy. 129 * 130 * @typedef OtaUpdatePolicy 131 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 132 * @stagemodelonly 133 * @since 12 134 */ 135 export interface OtaUpdatePolicy { 136 /** 137 * Software update type. 138 * 139 * @type { PolicyType } 140 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 141 * @stagemodelonly 142 * @since 12 143 */ 144 policyType: PolicyType; 145 146 /** 147 * Software version. 148 * 149 * @type { string } 150 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 151 * @stagemodelonly 152 * @since 12 153 */ 154 version: string; 155 156 /** 157 * The latest time of update. 158 * 159 * @type { ?number } 160 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 161 * @stagemodelonly 162 * @since 12 163 */ 164 latestUpdateTime?: number; 165 166 /** 167 * The time of delay update. 168 * 169 * @type { ?number } 170 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 171 * @stagemodelonly 172 * @since 12 173 */ 174 delayUpdateTime?: number; 175 176 /** 177 * The start time of installation window. 178 * 179 * @type { ?number } 180 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 181 * @stagemodelonly 182 * @since 12 183 */ 184 installStartTime?: number; 185 186 /** 187 * The end time of installation window. 188 * 189 * @type { ?number } 190 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 191 * @stagemodelonly 192 * @since 12 193 */ 194 installEndTime?: number; 195 } 196 197 /** 198 * The device system update package info. 199 * 200 * @typedef UpdatePackageInfo 201 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 202 * @stagemodelonly 203 * @since 12 204 */ 205 export interface UpdatePackageInfo { 206 /** 207 * The version of system update package. 208 * 209 * @type { string } 210 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 211 * @stagemodelonly 212 * @since 12 213 */ 214 version: string; 215 216 /** 217 * The detail of system update packages. 218 * 219 * @type { Array<Package> } 220 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 221 * @stagemodelonly 222 * @since 12 223 */ 224 packages: Array<Package>; 225 226 /** 227 * The description of system update package. 228 * 229 * @type { ?PackageDescription } 230 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 231 * @stagemodelonly 232 * @since 12 233 */ 234 description?: PackageDescription; 235 } 236 237 /** 238 * The detail of system update package. 239 * 240 * @typedef Package 241 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 242 * @stagemodelonly 243 * @since 12 244 */ 245 interface Package { 246 /** 247 * The type of system update package. 248 * 249 * @type { PackageType } 250 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 251 * @stagemodelonly 252 * @since 12 253 */ 254 type: PackageType; 255 256 /** 257 * The path of system update package. 258 * 259 * @type { string } 260 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 261 * @stagemodelonly 262 * @since 12 263 */ 264 path: string; 265 266 /** 267 * The file descriptor of system update package. 268 * 269 * @type { ?number } 270 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 271 * @stagemodelonly 272 * @since 12 273 */ 274 fd?: number; 275 } 276 277 /** 278 * Enum for system update package. 279 * 280 * @enum { number } 281 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 282 * @stagemodelonly 283 * @since 12 284 */ 285 enum PackageType { 286 /** 287 * FIRMWARE 288 * 289 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 290 * @stagemodelonly 291 * @since 12 292 */ 293 FIRMWARE = 1 294 } 295 296 /** 297 * The description of system update package. 298 * 299 * @typedef PackageDescription 300 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 301 * @stagemodelonly 302 * @since 12 303 */ 304 interface PackageDescription { 305 /** 306 * The custom notification of system update package. 307 * 308 * @type { ?NotifyDescription } 309 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 310 * @stagemodelonly 311 * @since 12 312 */ 313 notify?: NotifyDescription; 314 } 315 316 /** 317 * The custom notification of system update package. 318 * 319 * @typedef NotifyDescription 320 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 321 * @stagemodelonly 322 * @since 12 323 */ 324 interface NotifyDescription { 325 /** 326 * The custom notification tips of system update package. 327 * 328 * @type { ?string } 329 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 330 * @stagemodelonly 331 * @since 12 332 */ 333 installTips?: string; 334 335 /** 336 * The custom notification tips detail of system update package. 337 * 338 * @type { ?string } 339 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 340 * @stagemodelonly 341 * @since 12 342 */ 343 installTipsDetail?: string; 344 } 345 346 /** 347 * The result of system update. 348 * 349 * @typedef UpdateResult 350 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 351 * @stagemodelonly 352 * @since 12 353 */ 354 interface UpdateResult { 355 /** 356 * The current version of the system. 357 * 358 * @type { string } 359 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 360 * @stagemodelonly 361 * @since 12 362 */ 363 version: string; 364 365 /** 366 * The update status of the system. 367 * 368 * @type { UpdateStatus } 369 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 370 * @stagemodelonly 371 * @since 12 372 */ 373 status: UpdateStatus; 374 375 /** 376 * The update error message of the system. 377 * 378 * @type { ErrorInfo } 379 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 380 * @stagemodelonly 381 * @since 12 382 */ 383 errorInfo: ErrorInfo; 384 } 385 386 /** 387 * Enum for system update status. 388 * 389 * @enum { number } 390 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 391 * @stagemodelonly 392 * @since 12 393 */ 394 enum UpdateStatus { 395 /** 396 * The specified version system update package does not exist. 397 * 398 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 399 * @stagemodelonly 400 * @since 12 401 */ 402 NO_UPDATE_PACKAGE = -4, 403 404 /** 405 * The system update package waiting for installation. 406 * 407 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 408 * @stagemodelonly 409 * @since 12 410 */ 411 UPDATE_WAITING = -3, 412 413 /** 414 * The system is updating. 415 * 416 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 417 * @stagemodelonly 418 * @since 12 419 */ 420 UPDATING = -2, 421 422 /** 423 * The system update failed. 424 * 425 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 426 * @stagemodelonly 427 * @since 12 428 */ 429 UPDATE_FAILURE = -1, 430 431 /** 432 * The system update successful. 433 * 434 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 435 * @stagemodelonly 436 * @since 12 437 */ 438 UPDATE_SUCCESS = 0 439 } 440 441 /** 442 * The update error information of the system. 443 * 444 * @typedef ErrorInfo 445 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 446 * @stagemodelonly 447 * @since 12 448 */ 449 interface ErrorInfo { 450 /** 451 * The update error code of the system. 452 * 453 * @type { number } 454 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 455 * @stagemodelonly 456 * @since 12 457 */ 458 code: number; 459 460 /** 461 * The update error message of the system. 462 * 463 * @type { string } 464 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 465 * @stagemodelonly 466 * @since 12 467 */ 468 message: string; 469 } 470 471 /** 472 * Sets NTP server. 473 * This function can be called by a super administrator. 474 * 475 * @permission ohos.permission.ENTERPRISE_MANAGE_SYSTEM 476 * @param { Want } admin - admin indicates the enterprise admin extension ability information. 477 * The admin must have the corresponding permission. 478 * @param { string } server - the address of NTP server. 479 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 480 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 481 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 482 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 483 * 2. Incorrect parameter types; 3. Parameter verification failed. 484 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 485 * @stagemodelonly 486 * @since 12 487 */ 488 function setNTPServer(admin: Want, server: string): void; 489 490 /** 491 * Gets NTP server. 492 * This function can be called by a super administrator. 493 * 494 * @permission ohos.permission.ENTERPRISE_MANAGE_SYSTEM 495 * @param { Want } admin - admin indicates the enterprise admin extension ability information. 496 * The admin must have the corresponding permission. 497 * @returns { string } the address of NTP server. 498 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 499 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 500 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 501 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 502 * 2. Incorrect parameter types; 3. Parameter verification failed. 503 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 504 * @stagemodelonly 505 * @since 12 506 */ 507 function getNTPServer(admin: Want): string; 508 509 /** 510 * Sets device OTA update policy. 511 * This function can be called by a super administrator. 512 * 513 * @permission ohos.permission.ENTERPRISE_MANAGE_SYSTEM 514 * @param { Want } admin - admin indicates the enterprise admin extension ability information. 515 * The admin must have the corresponding permission. 516 * @param { OtaUpdatePolicy } policy - OTA update policy. 517 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 518 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 519 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 520 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 521 * 2. Incorrect parameter types; 3. Parameter verification failed. 522 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 523 * @stagemodelonly 524 * @since 12 525 */ 526 function setOtaUpdatePolicy(admin: Want, policy: OtaUpdatePolicy): void; 527 528 /** 529 * Gets device OTA update policy. 530 * This function can be called by a super administrator. 531 * 532 * @permission ohos.permission.ENTERPRISE_MANAGE_SYSTEM 533 * @param { Want } admin - admin indicates the enterprise admin extension ability information. 534 * The admin must have the corresponding permission. 535 * @returns { OtaUpdatePolicy } OTA update policy. 536 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 537 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 538 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 539 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 540 * 2. Incorrect parameter types; 3. Parameter verification failed. 541 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 542 * @stagemodelonly 543 * @since 12 544 */ 545 function getOtaUpdatePolicy(admin: Want): OtaUpdatePolicy; 546 547 /** 548 * Notifies the system of update packages information. 549 * This function can be called by a super administrator. 550 * 551 * @permission ohos.permission.ENTERPRISE_MANAGE_SYSTEM 552 * @param { Want } admin - admin indicates the administrator ability information. 553 * @param { UpdatePackageInfo } packageInfo - packageInfo indicates the information of system update package. 554 * @returns { Promise<void> } the promise returned by the notifyUpdatePackages. 555 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 556 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 557 * @throws { BusinessError } 9201004 - The update packages do not exist or analyzing failed. 558 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 559 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 560 * 2. Incorrect parameter types; 3. Parameter verification failed. 561 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 562 * @stagemodelonly 563 * @since 12 564 */ 565 function notifyUpdatePackages(admin: Want, packageInfo: UpdatePackageInfo): Promise<void>; 566 567 /** 568 * Gets the result of system update. 569 * This function can be called by a super administrator. 570 * 571 * @permission ohos.permission.ENTERPRISE_MANAGE_SYSTEM 572 * @param { Want } admin - admin indicates the administrator ability information. 573 * @param { string } version - version indicates the version of update. 574 * @returns { Promise<UpdateResult> } the promise returned by the getUpdateResult. 575 * @throws { BusinessError } 9200001 - The application is not an administrator application of the device. 576 * @throws { BusinessError } 9200002 - The administrator application does not have permission to manage the device. 577 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 578 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 579 * 2. Incorrect parameter types; 3. Parameter verification failed. 580 * @syscap SystemCapability.Customization.EnterpriseDeviceManager 581 * @stagemodelonly 582 * @since 12 583 */ 584 function getUpdateResult(admin: Want, version: string): Promise<UpdateResult>; 585} 586 587export default systemManager;