1# @ohos.enterprise.systemManager （系统管理）
2
3本模块提供系统管理能力。
4
5> **说明**：
6>
7> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> 本模块接口仅可在Stage模型下使用。
10>
11> 本模块接口仅对[设备管理应用](../../mdm/mdm-kit-guide.md#功能介绍)开放，需将设备管理应用激活后调用，实现相应功能。
12
13## 导入模块
14
15```ts
16import { systemManager } from '@kit.MDMKit';
17```
18
19## systemManager.setNTPServer
20
21setNTPServer(admin: Want, server: string): void
22
23指定设备管理应用设置NTP服务器的策略。
24
25**需要权限：** ohos.permission.ENTERPRISE_MANAGE_SYSTEM
26
27**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
28
29**参数：**
30
31| 参数名   | 类型                                  | 必填   | 说明      |
32| ----- | ----------------------------------- | ---- | ------- |
33| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是    | 设备管理应用。 |
34| server | string | 是 | NTP服务器地址（以","分隔，如"ntpserver1.com,ntpserver2.com"）。 |
35
36**错误码**：
37
38以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
39
40| 错误码ID | 错误信息                                                                      |
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**示例：**
48
49```ts
50import { systemManager } from '@kit.MDMKit';
51import { Want } from '@kit.AbilityKit';
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 usb policy. Code is ${err.code}, message is ${err.message}`);
62}
63```
64
65## systemManager.getNTPServer
66
67getNTPServer(admin: Want): string
68
69指定设备管理应用获取NTP服务器信息。
70
71**需要权限：** ohos.permission.ENTERPRISE_MANAGE_SYSTEM
72
73**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
74
75**参数：**
76
77| 参数名 | 类型                                | 必填 | 说明           |
78| ------ | ----------------------------------- | ---- | -------------- |
79| admin  | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 设备管理应用。 |
80
81**返回值：**
82
83| 类型   | 说明                            |
84| ------ | ------------------------------- |
85| string | string对象，返回NTP服务器信息。 |
86
87**错误码**：
88
89以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
90
91| 错误码ID | 错误信息                                                     |
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**示例：**
99
100```ts
101import { systemManager } from '@kit.MDMKit';
102import { Want } from '@kit.AbilityKit';
103import { BusinessError } from '@ohos.base';
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 set usb policy. Code is ${err.code}, message is ${err.message}`);
113}
114```
115
116## systemManager.setOtaUpdatePolicy
117
118setOtaUpdatePolicy(admin: Want, policy: OtaUpdatePolicy): void
119
120指定设备管理应用设置升级策略。内网升级场景下，需要先调用[systemManager.notifyUpdatePackages](#systemmanagernotifyupdatepackages)接口通知系统更新包，再调用该接口设置升级策略。
121
122**需要权限：** ohos.permission.ENTERPRISE_MANAGE_SYSTEM
123
124**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
125
126**参数：**
127
128| 参数名   | 类型                                  | 必填   | 说明      |
129| ----- | ----------------------------------- | ---- | ------- |
130| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是    | 设备管理应用。 |
131| policy | [OtaUpdatePolicy](#otaupdatepolicy) | 是 | 升级策略。 |
132
133**错误码**：
134
135以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
136
137| 错误码ID | 错误信息                                                                      |
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**示例：**
145
146```ts
147import { systemManager } from '@kit.MDMKit';
148import { Want } from '@kit.AbilityKit';
149let wantTemp: Want = {
150  bundleName: 'com.example.myapplication',
151  abilityName: 'EntryAbility',
152};
153// 默认升级策略
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// 禁止升级
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// 强制升级
176let otaUpdatePolicy3: systemManager.OtaUpdatePolicy = {
177  "policyType": systemManager.PolicyType.UPDATE_TO_SPECIFIC_VERSION,
178  "version": "version_1.0.0.2",
179  "latestUpdateTime": 1716343200, // 时间戳
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// 指定时间窗口升级
188let otaUpdatePolicy4: systemManager.OtaUpdatePolicy = {
189  "policyType": systemManager.PolicyType.WINDOWS,
190  "version": "version_1.0.0.3",
191  "installStartTime": 1716281049, // // 时间戳
192  "installEndTime": 1716343200, // // 时间戳
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// 延迟升级
201let otaUpdatePolicy5: systemManager.OtaUpdatePolicy = {
202  "policyType": systemManager.PolicyType.POSTPONE,
203  "version": "version_1.0.0.4",
204  "delayUpdateTime": 5, // 单位（小时）
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
213```
214
215## systemManager.getOtaUpdatePolicy
216
217getOtaUpdatePolicy(admin: Want): OtaUpdatePolicy
218
219指定设备管理应用查询升级策略。
220
221**需要权限：** ohos.permission.ENTERPRISE_MANAGE_SYSTEM
222
223**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
224
225**参数：**
226
227| 参数名 | 类型                                | 必填 | 说明           |
228| ------ | ----------------------------------- | ---- | -------------- |
229| admin  | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 设备管理应用。 |
230
231**返回值：**
232
233| 类型   | 说明                            |
234| ------ | ------------------------------- |
235| [OtaUpdatePolicy](#otaupdatepolicy) | OtaUpdatePolicy对象，返回升级策略。 |
236
237**错误码**：
238
239以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
240
241| 错误码ID | 错误信息                                                     |
242| -------- | ------------------------------------------------------------ |
243| 9200001  | The application is not an administrator application of the device.       |
244| 9200002  | The administrator application does not have permission to manage the device. |
245| 201 | Permission verification failed. The application does not have the permission required to call the API. |
246| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.|
247
248**示例：**
249
250```ts
251import { systemManager } from '@kit.MDMKit';
252import { Want } from '@kit.AbilityKit';
253let wantTemp: Want = {
254  bundleName: 'com.example.myapplication',
255  abilityName: 'EntryAbility',
256};
257try {
258  let policy: systemManager.OtaUpdatePolicy= systemManager.getOtaUpdatePolicy(wantTemp);
259  console.info(`Succeeded in getting update policy: ${JSON.stringify(policy)}`);
260} catch (err) {
261  console.error(`Failed to get update policy. Code is ${err.code}, message is ${err.message}`);
262}
263```
264
265## systemManager.notifyUpdatePackages
266
267notifyUpdatePackages(admin: Want, packageInfo: UpdatePackageInfo): Promise<void>
268
269通知系统更新包信息。内网升级场景下，需要先调用该接口通知系统更新包，再调用[systemManager.setOtaUpdatePolicy](#systemmanagersetotaupdatepolicy)设置升级策略。
270
271**需要权限：** ohos.permission.ENTERPRISE_MANAGE_SYSTEM
272
273**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
274
275**参数：**
276
277| 参数名 | 类型                                | 必填 | 说明           |
278| ------ | ----------------------------------- | ---- | -------------- |
279| admin  | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 设备管理应用。 |
280| packageInfo  | [UpdatePackageInfo](#updatepackageinfo) | 是   | 系统更新包信息。 |
281
282**返回值：**
283
284| 类型                   | 说明                      |
285| --------------------- | ------------------------- |
286| Promise<void> | 无返回结果的Promise对象。当通知系统更新包失败时会抛出错误对象。 |
287
288**错误码**：
289
290以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
291
292| 错误码ID | 错误信息                                                     |
293| -------- | ------------------------------------------------------------ |
294| 9200001  | The application is not an administrator application of the device.       |
295| 9200002  | The administrator application does not have permission to manage the device. |
296| 9201004  | The update packages do not exist or analyzing failed. |
297| 201 | Permission verification failed. The application does not have the permission required to call the API. |
298| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.|
299
300**示例：**
301
302```ts
303import { systemManager } from '@kit.MDMKit';
304import { BusinessError } from '@kit.BasicServicesKit';
305import { Want } from '@kit.AbilityKit';
306let wantTemp: Want = {
307  bundleName: 'com.example.myapplication',
308  abilityName: 'EntryAbility',
309};
310let notify: systemManager.NotifyDescription = {
311  "installTips": "installTips",
312  "installTipsDetail": "installTips detail"
313}
314let description: systemManager.PackageDescription = {
315  "notify": notify,
316}
317let updatePackages: Array<systemManager.Package> = [{
318  "type": systemManager.PackageType.FIRMWARE,
319  "path": "path",
320  "fd": 60,
321}]
322let updatePackageInfo: systemManager.UpdatePackageInfo = {
323  "version" : "1.0",
324  "packages" : updatePackages,
325  "description" : description,
326};
327systemManager.notifyUpdatePackages(wantTemp, updatePackageInfo).then(() => {
328  console.info('Succeeded in notifying update packages.');
329}).catch ((error: BusinessError) => {
330  console.error(`Failed to notify update packages. Code is ${error.code},message is ${error.message}`);
331});
332```
333
334## systemManager.getUpdateResult
335
336getUpdateResult(admin: Want, version: string): Promise&lt;UpdateResult&gt;
337
338获取系统更新结果。
339
340**需要权限：** ohos.permission.ENTERPRISE_MANAGE_SYSTEM
341
342**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
343
344**参数：**
345
346| 参数名 | 类型                                | 必填 | 说明           |
347| ------ | ----------------------------------- | ---- | -------------- |
348| admin  | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 设备管理应用。 |
349| version  | string | 是   | 更新包版本号。 |
350
351**返回值：**
352
353| 类型                   | 说明                      |
354| --------------------- | ------------------------- |
355| Promise&lt;[UpdateResult](#updateresult)&gt; | Promise对象，返回系统更新结果。 |
356
357**错误码**：
358
359以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
360
361| 错误码ID | 错误信息                                                     |
362| -------- | ------------------------------------------------------------ |
363| 9200001  | The application is not an administrator application of the device.       |
364| 9200002  | The administrator application does not have permission to manage the device. |
365| 201 | Permission verification failed. The application does not have the permission required to call the API. |
366| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.|
367
368**示例：**
369
370```ts
371import { systemManager } from '@kit.MDMKit';
372import { BusinessError } from '@kit.BasicServicesKit';
373import { Want } from '@kit.AbilityKit';
374let wantTemp: Want = {
375  bundleName: 'com.example.myapplication',
376  abilityName: 'EntryAbility',
377};
378systemManager.getUpdateResult(wantTemp, "1.0").then((result:systemManager.UpdateResult) => {
379    console.info(`Succeeded in getting update result: ${JSON.stringify(result)}`);
380  }).catch((error: BusinessError) => {
381    console.error(`Get update result failed. Code is ${error.code},message is ${error.message}`);
382  });
383```
384
385## SystemUpdateInfo
386
387待更新的系统版本信息。
388
389**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
390
391| 名称                | 类型     | 必填  | 说明            |
392| ----------------- | ------ | --- | ------------- |
393| versionName       | string | 是   | 待更新的系统版本名称。   |
394| firstReceivedTime | number | 是   | 首次收到系统更新包的时间。 |
395| packageType       | string | 是   | 待更新的系统更新包类型。  |
396
397## OtaUpdatePolicy
398
399升级策略。
400
401**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
402
403| 名称         | 类型     | 必填 | 说明                            |
404| ----------- | --------| ---- | ------------------------------- |
405| policyType        | [PolicyType](#policytype)   | 是   | 表示升级策略类型。 |
406| version | string   | 是   | 表示待升级软件版本号。 |
407| latestUpdateTime        | number   | 否   | 表示最晚升级时间（时间戳）。 |
408| delayUpdateTime | number   | 否   | 表示延迟升级时间（单位：小时）。 |
409| installStartTime        | number   | 否   | 表示指定安装窗口起始时间（时间戳）。 |
410| installEndTime | number   | 否   | 表示指定安装窗口结束时间（时间戳）。 |
411
412## PolicyType
413
414升级策略类型枚举。
415
416**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
417
418| 名称                | 值  | 说明    |
419| ----------------- | ---- | ----- |
420| DEFAULT | 0 | 默认升级策略。周期提示用户，用户确认后升级。 |
421| PROHIBIT  | 1 | 禁止升级策略。 |
422| UPDATE_TO_SPECIFIC_VERSION | 2 | 强制升级策略。需指定最晚升级时间（latestUpdateTime）参数。 |
423| WINDOWS | 3 | 指定时间窗口升级策略。需指定时间窗口参数（installStartTime、installEndTime）。 |
424| POSTPONE | 4 | 延迟升级策略。延迟指定时间（delayUpdateTime）后进入DEFAULT模式，周期提示用户升级。 |
425
426## UpdatePackageInfo
427
428系统更新包信息。
429
430**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
431
432| 名称                | 类型     | 必填  | 说明            |
433| ----------------- | ------ | --- | ------------- |
434| version       | string | 是   | 系统更新包版本号。   |
435| packages | Array&lt;[Package](#package)&gt; | 是   | 系统更新包详情。 |
436| description       | [PackageDescription](#packagedescription) | 否   | 系统更新包描述信息。  |
437
438## Package
439
440系统更新包详情。
441
442**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
443
444| 名称                | 类型     | 必填  | 说明            |
445| ----------------- | ------ | --- | ------------- |
446| type       | [PackageType](#packagetype) | 是   | 系统更新包类型。   |
447| path | string | 是   | 系统更新包文件路径。若传入fd参数，该参数传入更新包文件名。 |
448| fd       | number | 否   | 系统更新包文件句柄。当前不支持只传入path参数，需要传入fd。  |
449
450## PackageDescription
451
452系统更新包描述信息。
453
454**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
455
456| 名称                | 类型     | 必填  | 说明            |
457| ----------------- | ------ | --- | ------------- |
458| notify       | [NotifyDescription](#notifydescription) | 否   | 企业自定义更新通知说明。   |
459
460## NotifyDescription
461
462企业自定义更新通知说明。
463
464**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
465
466| 名称                | 类型     | 必填  | 说明            |
467| ----------------- | ------ | --- | ------------- |
468| installTips       | string | 否   | 企业自定义更新提示。   |
469| installTipsDetail       | string | 否   | 企业自定义更新提示详情。   |
470
471## UpdateResult
472
473系统更新结果信息。
474
475**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
476
477| 名称                | 类型   | 可读  | 可写   | 说明            |
478| ----------------- | ------ | ------ | ------ | ------------- |
479| version       | string |  是 | 否 |系统当前版本号。   |
480| status       | [UpdateStatus](#updatestatus) | 是 | 否 | 系统更新状态。   |
481| errorInfo       | [ErrorInfo](#errorinfo) | 是 | 否 | 系统更新错误信息。   |
482
483## ErrorInfo
484
485系统更新错误信息。
486
487**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
488
489| 名称                | 类型     | 可读  | 可写 | 说明            |
490| ----------------- | ------ | ------ | ------ | ------------- |
491| code       | number | 是 | 否 | 错误码。   |
492| message       | string | 是 | 否 | 错误描述信息。   |
493
494## PackageType
495
496系统更新包类型。
497
498**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
499
500| 名称                | 值  | 说明    |
501| ----------------- | ---- | ----- |
502| FIRMWARE | 1 | 固件。 |
503
504## UpdateStatus
505
506系统更新状态。
507
508**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
509
510| 名称               | 值  | 说明    |
511| -----------------  | ---- | ----- |
512| NO_UPDATE_PACKAGE  | -4 | 指定版本系统更新包不存在。 |
513| UPDATE_WAITING     | -3 | 系统更新包等待安装中。 |
514| UPDATING           | -2 | 正在更新。 |
515| UPDATE_FAILURE     | -1 | 更新失败。 |
516| UPDATE_SUCCESS     | 0 | 更新成功。 |
517