1# @ohos.enterprise.systemManager (System Management) 2 3The **systemManager** module provides system management capabilities. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 12. 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 of this module can be called only by a device administrator application that is enabled. For details, see [MDM Kit Development](../../mdm/mdm-kit-guide.md). 12 13## Modules to Import 14 15```ts 16import { systemManager } from '@kit.MDMKit'; 17``` 18 19## systemManager.setNTPServer 20 21setNTPServer(admin: Want, server: string): void 22 23Sets the NTP server. 24 25**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SYSTEM 26 27**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 28 29**Parameters** 30 31| Name | Type | Mandatory | Description | 32| ----- | ----------------------------------- | ---- | ------- | 33| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility.| 34| server | string | Yes| NTP server addresses separated by a comma (,). For example, **ntpserver1.com,ntpserver2.com**. The value can contain a maximum of 96 bytes (including the end character).| 35 36**Error codes** 37 38For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 39 40| ID| Error Message | 41| ------- | ---------------------------------------------------------------------------- | 42| 9200001 | The application is not an administrator application of the device. | 43| 9200002 | The administrator application does not have permission to manage the device. | 44| 201 | Permission verification failed. The application does not have the permission required to call the API. | 45| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 46 47**Example** 48 49```ts 50import { Want } from '@kit.AbilityKit'; 51 52let wantTemp: Want = { 53 bundleName: 'com.example.myapplication', 54 abilityName: 'EntryAbility', 55}; 56let server: string = "ntpserver.com"; 57try { 58 systemManager.setNTPServer(wantTemp, server); 59 console.info('Succeeded in setting NTPserver.'); 60} catch (err) { 61 console.error(`Failed to set ntp server. Code is ${err.code}, message is ${err.message}`); 62} 63``` 64 65## systemManager.getNTPServer 66 67getNTPServer(admin: Want): string 68 69Obtains the NTP server information. 70 71**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SYSTEM 72 73**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 74 75**Parameters** 76 77| Name| Type | Mandatory| Description | 78| ------ | ------------------------------------------------------- | ---- | ---------------------- | 79| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility.| 80 81**Return value** 82 83| Type | Description | 84| ------ | ----------------------------------- | 85| string | NTP server information.| 86 87**Error codes** 88 89For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 90 91| ID| Error Message | 92| -------- | ------------------------------------------------------------ | 93| 9200001 | The application is not an administrator application of the device. | 94| 9200002 | The administrator application does not have permission to manage the device. | 95| 201 | Permission verification failed. The application does not have the permission required to call the API. | 96| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 97 98**Example** 99 100```ts 101import { Want } from '@kit.AbilityKit'; 102import { BusinessError } from '@ohos.base'; 103 104let wantTemp: Want = { 105 bundleName: 'com.example.myapplication', 106 abilityName: 'EntryAbility', 107}; 108try { 109 systemManager.getNTPServer(wantTemp); 110 console.info('Succeeded in getting NTP server.'); 111} catch (err) { 112 console.error(`Failed to get ntp server. Code is ${err.code}, message is ${err.message}`); 113} 114``` 115 116## systemManager.setOtaUpdatePolicy 117 118setOtaUpdatePolicy(admin: Want, policy: OtaUpdatePolicy): void 119 120Sets the update policy. In intranet updates, call [systemManager.notifyUpdatePackages](#systemmanagernotifyupdatepackages) to notify the system of the update packages and then call this API to set the upgrade policy. 121 122**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SYSTEM 123 124**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 125 126**Parameters** 127 128| Name | Type | Mandatory | Description | 129| ----- | ----------------------------------- | ---- | ------- | 130| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility.| 131| policy | [OtaUpdatePolicy](#otaupdatepolicy) | Yes| OTA update policy to set.| 132 133**Error codes** 134 135For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 136 137| ID| Error Message | 138| ------- | ---------------------------------------------------------------------------- | 139| 9200001 | The application is not an administrator application of the device. | 140| 9200002 | The administrator application does not have permission to manage the device. | 141| 201 | Permission verification failed. The application does not have the permission required to call the API. | 142| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 143 144**Example** 145 146```ts 147import { Want } from '@kit.AbilityKit'; 148 149let wantTemp: Want = { 150 bundleName: 'com.example.myapplication', 151 abilityName: 'EntryAbility', 152}; 153// Default update policy. 154let otaUpdatePolicy1: systemManager.OtaUpdatePolicy = { 155 "policyType": systemManager.PolicyType.DEFAULT, 156 "version": "version_1.0.0.0", 157}; 158try { 159 systemManager.setOtaUpdatePolicy(wantTemp, otaUpdatePolicy1); 160 console.info('Succeeded in setting ota update policy.'); 161} catch (err) { 162 console.error(`Failed to set ota update policy. Code is ${err.code}, message is ${err.message}`); 163} 164// Prohibit update. 165let otaUpdatePolicy2: systemManager.OtaUpdatePolicy = { 166 "policyType": systemManager.PolicyType.PROHIBIT, 167 "version": "version_1.0.0.1", 168}; 169try { 170 systemManager.setOtaUpdatePolicy(wantTemp, otaUpdatePolicy2); 171 console.info('Succeeded in setting ota update policy.'); 172} catch (err) { 173 console.error(`Failed to set ota update policy. Code is ${err.code}, message is ${err.message}`); 174} 175// Enforce update. 176let otaUpdatePolicy3: systemManager.OtaUpdatePolicy = { 177 "policyType": systemManager.PolicyType.UPDATE_TO_SPECIFIC_VERSION, 178 "version": "version_1.0.0.2", 179 "latestUpdateTime": 1716343200, // Timestamp 180}; 181try { 182 systemManager.setOtaUpdatePolicy(wantTemp, otaUpdatePolicy3); 183 console.info('Succeeded in setting ota update policy.'); 184} catch (err) { 185 console.error(`Failed to set ota update policy. Code is ${err.code}, message is ${err.message}`); 186} 187// Update at the specified time period. 188let otaUpdatePolicy4: systemManager.OtaUpdatePolicy = { 189 "policyType": systemManager.PolicyType.WINDOWS, 190 "version": "version_1.0.0.3", 191 "installStartTime": 1716281049, // Timestamp 192 "installEndTime": 1716343200, // Timestamp 193}; 194try { 195 systemManager.setOtaUpdatePolicy(wantTemp, otaUpdatePolicy4); 196 console.info('Succeeded in setting ota update policy.'); 197} catch (err) { 198 console.error(`Failed to set ota update policy. Code is ${err.code}, message is ${err.message}`); 199} 200// Delay the update. 201let otaUpdatePolicy5: systemManager.OtaUpdatePolicy = { 202 "policyType": systemManager.PolicyType.POSTPONE, 203 "version": "version_1.0.0.4", 204 "delayUpdateTime": 5, // Time for which the update is delayed, in hours. 205}; 206try { 207 systemManager.setOtaUpdatePolicy(wantTemp, otaUpdatePolicy5); 208 console.info('Succeeded in setting ota update policy.'); 209} catch (err) { 210 console.error(`Failed to set ota update policy. Code is ${err.code}, message is ${err.message}`); 211} 212// Disable public network upgrade. 213let otaUpdatePolicy6: systemManager.OtaUpdatePolicy = { 214 "policyType": systemManager.PolicyType.DEFAULT, 215 "version": "version_1.0.0.5", 216 "disableSystemOtaUpdate": true, 217}; 218try { 219 systemManager.setOtaUpdatePolicy(wantTemp, otaUpdatePolicy6); 220 console.info('Succeeded in setting ota update policy.'); 221} catch (err) { 222 console.error(`Failed to set ota update policy. Code is ${err.code}, message is ${err.message}`); 223} 224``` 225 226## systemManager.getOtaUpdatePolicy 227 228getOtaUpdatePolicy(admin: Want): OtaUpdatePolicy 229 230Queries the update policy. 231 232**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SYSTEM 233 234**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 235 236**Parameters** 237 238| Name| Type | Mandatory| Description | 239| ------ | ------------------------------------------------------- | ---- | ------------------ | 240| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility.| 241 242**Return value** 243 244| Type | Description | 245| ------ | ------------------------------- | 246| [OtaUpdatePolicy](#otaupdatepolicy) | **OtaUpdatePolicy** object containing the update policy obtained.| 247 248**Error codes** 249 250For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 251 252| ID| Error Message | 253| -------- | ------------------------------------------------------------ | 254| 9200001 | The application is not an administrator application of the device. | 255| 9200002 | The administrator application does not have permission to manage the device. | 256| 201 | Permission verification failed. The application does not have the permission required to call the API. | 257| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 258 259**Example** 260 261```ts 262import { Want } from '@kit.AbilityKit'; 263 264let wantTemp: Want = { 265 bundleName: 'com.example.myapplication', 266 abilityName: 'EntryAbility', 267}; 268try { 269 let policy: systemManager.OtaUpdatePolicy= systemManager.getOtaUpdatePolicy(wantTemp); 270 console.info(`Succeeded in getting update policy: ${JSON.stringify(policy)}`); 271} catch (err) { 272 console.error(`Failed to get update policy. Code is ${err.code}, message is ${err.message}`); 273} 274``` 275 276## systemManager.notifyUpdatePackages 277 278notifyUpdatePackages(admin: Want, packageInfo: UpdatePackageInfo): Promise<void> 279 280Notifies the system of the update packages. In intranet updates, call this API to notify the system of the update packages, and then call [systemManager.setOtaUpdatePolicy](#systemmanagersetotaupdatepolicy) to set the update policy. 281 282**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SYSTEM 283 284**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 285 286**Parameters** 287 288| Name| Type | Mandatory| Description | 289| ------ | ----------------------------------- | ---- | -------------- | 290| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility.| 291| packageInfo | [UpdatePackageInfo](#updatepackageinfo) | Yes | Information about the system update packages.| 292 293**Return value** 294 295| Type | Description | 296| --------------------- | ------------------------- | 297| Promise<void> | Promise that returns no value. An error object will be thrown if the operation fails.| 298 299**Error codes** 300 301For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 302 303| ID| Error Message | 304| -------- | ------------------------------------------------------------ | 305| 9200001 | The application is not an administrator application of the device. | 306| 9200002 | The administrator application does not have permission to manage the device. | 307| 9201004 | The update packages do not exist or analyzing failed. | 308| 201 | Permission verification failed. The application does not have the permission required to call the API. | 309| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 310 311**Example** 312 313```ts 314import { BusinessError } from '@kit.BasicServicesKit'; 315import { Want } from '@kit.AbilityKit'; 316 317let wantTemp: Want = { 318 bundleName: 'com.example.myapplication', 319 abilityName: 'EntryAbility', 320}; 321let notify: systemManager.NotifyDescription = { 322 "installTips": "installTips", 323 "installTipsDetail": "installTips detail" 324} 325let description: systemManager.PackageDescription = { 326 "notify": notify, 327} 328let updatePackages: Array<systemManager.Package> = [{ 329 "type": systemManager.PackageType.FIRMWARE, 330 "path": "path", 331 "fd": 60, 332}] 333let updatePackageInfo: systemManager.UpdatePackageInfo = { 334 "version" : "1.0", 335 "packages" : updatePackages, 336 "description" : description, 337}; 338systemManager.notifyUpdatePackages(wantTemp, updatePackageInfo).then(() => { 339 console.info('Succeeded in notifying update packages.'); 340}).catch ((error: BusinessError) => { 341 console.error(`Failed to notify update packages. Code is ${error.code},message is ${error.message}`); 342}); 343``` 344 345## systemManager.getUpdateResult 346 347getUpdateResult(admin: Want, version: string): Promise<UpdateResult> 348 349Obtains the system update result. 350 351**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SYSTEM 352 353**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 354 355**Parameters** 356 357| Name| Type | Mandatory| Description | 358| ------ | ----------------------------------- | ---- | -------------- | 359| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility.| 360| version | string | Yes | Version of the update package.| 361 362**Return value** 363 364| Type | Description | 365| --------------------- | ------------------------- | 366| Promise<[UpdateResult](#updateresult)> | Promise used to return the system update result.| 367 368**Error codes** 369 370For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 371 372| ID| Error Message | 373| -------- | ------------------------------------------------------------ | 374| 9200001 | The application is not an administrator application of the device. | 375| 9200002 | The administrator application does not have permission to manage the device. | 376| 201 | Permission verification failed. The application does not have the permission required to call the API. | 377| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 378 379**Example** 380 381```ts 382import { BusinessError } from '@kit.BasicServicesKit'; 383import { Want } from '@kit.AbilityKit'; 384 385let wantTemp: Want = { 386 bundleName: 'com.example.myapplication', 387 abilityName: 'EntryAbility', 388}; 389systemManager.getUpdateResult(wantTemp, "1.0").then((result:systemManager.UpdateResult) => { 390 console.info(`Succeeded in getting update result: ${JSON.stringify(result)}`); 391 }).catch((error: BusinessError) => { 392 console.error(`Get update result failed. Code is ${error.code},message is ${error.message}`); 393 }); 394``` 395## systemManager.getUpdateAuthData<sup>19+</sup> 396 397getUpdateAuthData(admin: Want): Promise<string> 398 399Obtains the authentication data for system update verification. This API uses a promise to return the result. 400 401**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SYSTEM 402 403**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 404 405**Parameters** 406 407| Name| Type | Mandatory| Description | 408| ------ | ----------------------------------- | ---- | -------------- | 409| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility.| 410 411**Return value** 412 413| Type | Description | 414| --------------------- | ------------------------- | 415| Promise<string> | Promise used to return the authentication data.| 416 417**Error codes** 418 419For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 420 421| ID| Error Message | 422| -------- | ------------------------------------------------------------ | 423| 9200001 | The application is not an administrator application of the device. | 424| 9200002 | The administrator application does not have permission to manage the device. | 425| 201 | Permission verification failed. The application does not have the permission required to call the API. | 426 427**Example** 428 429```ts 430import { BusinessError } from '@kit.BasicServicesKit'; 431import { Want } from '@kit.AbilityKit'; 432 433let wantTemp: Want = { 434 bundleName: 'com.example.myapplication', 435 abilityName: 'EntryAbility', 436}; 437systemManager.getUpdateAuthData(wantTemp).then((result: string) => { 438 console.info(`Succeeded in getting update auth data: ${JSON.stringify(result)}`); 439 }).catch((error: BusinessError) => { 440 console.error(`Get update auth data failed. Code is ${error.code},message is ${error.message}`); 441 }); 442``` 443## SystemUpdateInfo 444 445Represents information about the system version to update. 446 447**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 448 449| Name | Type | Read-Only | Optional| Description | 450| ----------------- | ------ | --- | --- |------------- | 451| versionName | string | No | No|System version to update. | 452| firstReceivedTime | number | No | No|Time when the system update package is received for the first time.| 453| packageType | string | No | No|Type of the system update package to update. | 454 455## OtaUpdatePolicy 456 457Represents an OTA update policy. 458 459**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 460 461| Name | Type | Read-Only| Optional| Description | 462| ----------- | --------| ---- | -----| -------------------------- | 463| policyType | [PolicyType](#policytype) | No | No| Type of the update policy.| 464| version | string | No | No|Version of the software to update.| 465| latestUpdateTime | number | No | Yes| Latest update time (timestamp).| 466| delayUpdateTime | number | No | Yes| Period for which the update is postponed, in hours.| 467| installStartTime | number | No | Yes| Start time (timestamp) of the installation window.| 468| installEndTime | number | No | Yes| End time (timestamp) of the installation window.| 469| disableSystemOtaUpdate<sup>20+</sup> | boolean | No | Yes| Whether to disable public network upgrade. <br>The value **true** means to disable public network upgrade; the value **false** (default) means the opposite. If public network upgrade is disabled, you can perform intranet upgrade.| 470 471## PolicyType 472 473Enumerates the update policy types. 474 475**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 476 477| Name | Value | Description | 478| ----------------- | ---- | ----- | 479| DEFAULT | 0 | Default update policy, which periodically notifies the user of the update and starts the update after user confirmation.| 480| PROHIBIT | 1 | Prohibit updates.| 481| UPDATE_TO_SPECIFIC_VERSION | 2 | Enforce updates. In this case, **latestUpdateTime** must be specified.| 482| WINDOWS | 3 | Update at the specified time window. In this case, **installStartTime** and **installEndTime** must be specified.| 483| POSTPONE | 4 | Postpone updates. After the time specified by **delayUpdateTime** is over, the default update policy is used.| 484 485## UpdatePackageInfo 486 487Represents information about the system update packages. 488 489**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 490 491| Name | Type | Read-Only | Optional| Description | 492| ----------------- | ------ | --- | ---- |------------- | 493| version | string | No | No| Version of the system update package. | 494| packages | Array<[Package](#package)> | No | No| Details about the system update packages.| 495| description | [PackageDescription](#packagedescription) | No | Yes| Description of the system update packages. | 496| authInfo<sup>19+</sup> | string | No| Yes| Authentication information of the system update package.| 497 498## Package 499 500Represents the details about a system update package. 501 502**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 503 504| Name | Type | Read-Only | Optional| Description | 505| ----------------- | ------ | --- | --- | ------------- | 506| type | [PackageType](#packagetype) | No | No| Type of the system update package. | 507| path | string | No | No| Path of the system update package. If **fd** is specified, pass in the update package name here.| 508| fd | number | No | Yes| File descriptor (FD) of the system update package. Currently, you cannot pass in **path** only. The **fd** parameter must also be passed in. | 509 510## PackageDescription 511 512Represents the description of a system update package. 513 514**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 515 516| Name | Type | Read-Only | Optional| Description | 517| ----------------- | ------ | --- | --- | ------------- | 518| notify | [NotifyDescription](#notifydescription) | No | Yes| Update notification defined by an enterprise. | 519 520## NotifyDescription 521 522Represents the update notification defined by an enterprise. 523 524**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 525 526| Name | Type | Read-Only | Optional| Description | 527| ----------------- | ------ | --- | ---- | ------------- | 528| installTips | string | No | Yes| Update tips provided by the enterprise. | 529| installTipsDetail | string | No | Yes| Details about the update tips customized by the enterprise. | 530 531## UpdateResult 532 533Represents the update result information. 534 535**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 536 537| Name | Type | Read-Only | Optional | Description | 538| ----------------- | ------ | ------ | ------ | ------------- | 539| version | string | No| No|Current version of the system. | 540| status | [UpdateStatus](#updatestatus) | No| No| System update status. | 541| errorInfo | [ErrorInfo](#errorinfo) | No| No| Error information. | 542 543## ErrorInfo 544 545Represents the update error information. 546 547**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 548 549| Name | Type | Read-Only | Optional| Description | 550| ----------------- | ------ | ------ | ------ | ------------- | 551| code | number | No| No| Error code. | 552| message | string | No| No| Error message. | 553 554## PackageType 555 556Enumerates the update package types. 557 558**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 559 560| Name | Value | Description | 561| ----------------- | ---- | ----- | 562| FIRMWARE | 1 | Firmware.| 563 564## UpdateStatus 565 566Enumerates the system update statuses. 567 568**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 569 570| Name | Value | Description | 571| ----------------- | ---- | ----- | 572| NO_UPDATE_PACKAGE | -4 | The system update package of the specified version does not exist.| 573| UPDATE_WAITING | -3 | The system update package is waiting to be installed.| 574| UPDATING | -2 | The system update is being performed.| 575| UPDATE_FAILURE | -1 | The update failed.| 576| UPDATE_SUCCESS | 0 | The update is successful.| 577