• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.bundle.bundleMonitor (bundleMonitor) (System API)
2<!--Kit: Ability Kit-->
3<!--Subsystem: BundleManager-->
4<!--Owner: @wanghang904-->
5<!--Designer: @hanfeng6-->
6<!--Tester: @kongjing2-->
7<!--Adviser: @Brilliantry_Rui-->
8
9The module provides APIs for listens for bundle installation, uninstall, and updates.
10
11> **NOTE**
12>
13> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
14>
15> The APIs provided by this module are system APIs.
16
17## Modules to Import
18
19```ts
20import bundleMonitor from '@ohos.bundle.bundleMonitor';
21```
22
23## BundleChangedInfo
24
25**System capability**: SystemCapability.BundleManager.BundleFramework.Core
26
27**System API**: This is a system API.
28
29| Name      | Type  | Read-Only| Optional| Description                      |
30| ---------- | ------ | ---- | ---- | -------------------------- |
31| bundleName | string | Yes  | No  | Name of the bundle whose status changes.|
32| userId     | number | Yes  | No  | ID of the user for whom the bundle status changes. You can obtain the ID by calling [getOsAccountLocalId](../apis-basic-services-kit/js-apis-osAccount.md#getosaccountlocalid9).  |
33| appIndex<sup>12+</sup>   | number | Yes  | No  |  Index of the application clone whose status changes. |
34
35## BundleChangedEvent
36
37Enumerates the types of events to listen for.
38
39**System capability**: SystemCapability.BundleManager.BundleFramework.Core
40
41**System API**: This is a system API.
42
43| Name      | Description            |
44| ---------- | --------------- |
45| add        | Bundle installation event.  |
46| update     | Bundle update event.  |
47| remove     | Bundle uninstall event.  |
48
49## bundleMonitor.on
50
51on(type: BundleChangedEvent, callback: Callback\<BundleChangedInfo>): void
52
53Subscribes to bundle installation, uninstall, and update events.
54>**NOTE**
55>
56>This API must be used together with [bundleMonitor.off](#bundlemonitoroff). When the lifecycle of a component, page, or application ends, use [bundleMonitor.off](#bundlemonitoroff) to unsubscribe from the bundle installation, uninstall, and update events.
57
58**Required permissions**: ohos.permission.LISTEN_BUNDLE_CHANGE
59
60**System API**: This is a system API.
61
62**System capability**: SystemCapability.BundleManager.BundleFramework.Core
63
64**Parameters**
65
66| Name                      | Type    | Mandatory| Description              |
67| ---------------------------- | -------- | ---- | ------------------ |
68| type| [BundleChangedEvent](js-apis-bundleMonitor-sys.md#bundlechangedevent)| Yes  | Type of the event to subscribe to.|
69| callback | callback\<BundleChangedInfo>| Yes  | [Callback function](../apis-basic-services-kit/js-apis-base.md#asynccallback) used for the subscription.|
70
71**Error codes**
72
73For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
74
75| ID| Error Message                           |
76| -------- | --------------------------------------|
77| 201 | Verify permission denied. |
78| 202 | Permission denied, non-system app called system api. |
79| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
80
81**Example**
82
83```ts
84import bundleMonitor from '@ohos.bundle.bundleMonitor';
85import { BusinessError } from '@ohos.base';
86let callbackFun = (bundleChangeInfo: bundleMonitor.BundleChangedInfo) => {
87  console.info(`bundleName : ${bundleChangeInfo.bundleName} userId : ${bundleChangeInfo.userId}`);
88};
89try {
90    bundleMonitor.on('add', callbackFun);
91} catch (errData) {
92    let message = (errData as BusinessError).message;
93    let errCode = (errData as BusinessError).code;
94    console.error(`errData is errCode:${errCode}  message:${message}`);
95}
96```
97
98## bundleMonitor.off
99
100off(type: BundleChangedEvent, callback?: Callback\<BundleChangedInfo>): void
101
102Unsubscribes from bundle installation, uninstall, and update events.
103
104**Required permissions**: ohos.permission.LISTEN_BUNDLE_CHANGE
105
106**System API**: This is a system API.
107
108**System capability**: SystemCapability.BundleManager.BundleFramework.Core
109
110**Parameters**
111
112| Name                      | Type    | Mandatory| Description                                                      |
113| ---------------------------- | -------- | ---- | ---------------------------------------------------------- |
114| type| [BundleChangedEvent](js-apis-bundleMonitor-sys.md#bundlechangedevent)| Yes  | Type of the event to unsubscribe from.                                        |
115| callback | callback\<BundleChangedInfo>| No  | [Callback function](../apis-basic-services-kit/js-apis-base.md#asynccallback) used for the unsubscription. If this parameter is left empty, all callbacks of the current event are unsubscribed from.|
116
117**Error codes**
118
119For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
120
121| ID| Error Message                           |
122| -------- | --------------------------------------|
123| 201 | Verify permission denied. |
124| 202 | Permission denied, non-system app called system api. |
125| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
126
127**Example**
128
129```ts
130import bundleMonitor from '@ohos.bundle.bundleMonitor';
131import { BusinessError } from '@ohos.base';
132
133// The variable in this API must be the same as that in bundleMonitor.on. Otherwise, the callback cannot be unsubscribed from.
134let callbackFun = (bundleChangeInfo: bundleMonitor.BundleChangedInfo) => {
135  console.info(`bundleName : ${bundleChangeInfo.bundleName} userId : ${bundleChangeInfo.userId}`);
136};
137
138try {
139    bundleMonitor.off('add', callbackFun);
140} catch (errData) {
141    let message = (errData as BusinessError).message;
142    let errCode = (errData as BusinessError).code;
143    console.error(`errData is errCode:${errCode}  message:${message}`);
144}
145```
146