1# @ohos.bundle.freeInstall (freeInstall) (System API)
2
3The **Bundle.freeInstall** module provides APIs for setting and obtaining installation-free information and APIs for obtaining **BundlePackInfo** and **DispatchInfo**.
4
5> **NOTE**
6>
7> 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.
8>
9> The APIs provided by this module are system APIs.
10
11## Modules to Import
12
13```js
14import freeInstall from '@ohos.bundle.freeInstall';
15```
16
17## Required Permissions
18
19| Permission                                      | APL    | Description              |
20| ------------------------------------------ | ------------ | ------------------ |
21| ohos.permission.GET_BUNDLE_INFO_PRIVILEGED | system_basic | Permission to query information about all applications. |
22| ohos.permission.INSTALL_BUNDLE             | system_core  | Permission to install or uninstall other applications except enterprise applications, including enterprise InHouse, mobile device management (MDM), and Normal applications.  |
23
24For details about the APL, see [Basic Concepts in the Permission Mechanism](../../security/AccessToken/app-permission-mgmt-overview.md#basic-concepts-in-the-permission-mechanism).
25## UpgradeFlag
26
27**System API**: This is a system API.
28
29**System capability**: SystemCapability.BundleManager.BundleFramework.FreeInstall
30
31| Name            | Value  | Description            |
32| ---------------- | ---- | ---------------- |
33| NOT_UPGRADE      | 0    | No module needs an upgrade.    |
34| SINGLE_UPGRADE   | 1    | A single module needs an upgrade. |
35| RELATION_UPGRADE | 2    | The module that has a relationship with the current one needs an upgrade. |
36
37## BundlePackFlag
38
39**System API**: This is a system API.
40
41**System capability**: SystemCapability.BundleManager.BundleFramework.FreeInstall
42
43| Name              | Value        | Description                              |
44| ------------------ | ---------- | ---------------------------------- |
45| GET_PACK_INFO_ALL  | 0x00000000 | All information in the **pack.info** file.   |
46| GET_PACKAGES       | 0x00000001 | Package information in the **pack.info** file. |
47| GET_BUNDLE_SUMMARY | 0x00000002 | Bundle summary information in the **pack.info** file. |
48| GET_MODULE_SUMMARY | 0x00000004 | Module summary information in the **pack.info** file. |
49
50## freeInstall.setHapModuleUpgradeFlag
51
52setHapModuleUpgradeFlag(bundleName: string, moduleName: string, upgradeFlag: UpgradeFlag, callback: AsyncCallback\<void>):void
53
54Sets an upgrade flag for a module. This API uses an asynchronous callback to return the result.
55
56**Required permissions**: ohos.permission.INSTALL_BUNDLE
57
58**System API**: This is a system API.
59
60**System capability**: SystemCapability.BundleManager.BundleFramework.FreeInstall
61
62**Parameters**
63
64| Name    | Type                       | Mandatory | Description                      |
65| ----------- | --------------------------- | ---- | ---------------------------- |
66| bundleName  | string                      | Yes  | Bundle name.    |
67| moduleName  | string                      | Yes  | Module name.          |
68| upgradeFlag | [UpgradeFlag](#upgradeflag) | Yes  | Upgrade flag, which is for internal use only.      |
69| callback    | AsyncCallback\<void>        | Yes  | Callback used to return the result. If the operation is successful, **err** is **null**; otherwise, **err** is an error object. |
70
71**Error codes**
72
73For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
74
75| ID |    Error Message                           |
76|----------|---------------------------------------- |
77| 201 | 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| 801 | Capability not supported. |
81| 17700001 | The specified bundle name is not found. |
82| 17700002 | The specified module name is not found. |
83
84**Example**
85
86```js
87import freeInstall from '@ohos.bundle.freeInstall';
88let bundleName = 'com.example.myapplication';
89let moduleName = 'entry';
90let upgradeFlag = freeInstall.UpgradeFlag.SINGLE_UPGRADE;
91try {
92    freeInstall.setHapModuleUpgradeFlag(bundleName, moduleName, upgradeFlag, err => {
93        if (err) {
94            console.error('Operation failed:' + JSON.stringify(err));
95        } else {
96            console.info('Operation succeed');
97        }
98    });
99} catch (err) {
100    console.error('Operation failed:' + JSON.stringify(err));
101}
102```
103
104## setHapModuleUpgradeFlag
105
106setHapModuleUpgradeFlag(bundleName: string, moduleName: string, upgradeFlag: UpgradeFlag): Promise\<void>
107
108Sets an upgrade flag for a module. This API uses a promise to return the result.
109
110**System API**: This is a system API.
111
112**Required permissions**: ohos.permission.INSTALL_BUNDLE
113
114**System capability**: SystemCapability.BundleManager.BundleFramework.FreeInstall
115
116**Parameters**
117
118| Name     | Type                       | Mandatory | Description                  |
119| ----------- | --------------------------- | ---- | ---------------------- |
120| bundleName  | string                      | Yes  | Bundle name. |
121| moduleName  | string                      | Yes  | Module name.    |
122| upgradeFlag | [UpgradeFlag](#upgradeflag) | Yes  | Upgrade flag, which is for internal use only.|
123
124**Return value**
125
126| Type         | Description                                |
127| ------------- | ------------------------------------ |
128| Promise\<void> | Promise that returns no value. |
129
130**Error codes**
131
132For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
133
134| ID |    Error Message                           |
135|----------|----------------------------------------|
136| 201 | Permission denied. |
137| 202 | Permission denied, non-system app called system api. |
138| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
139| 801 | Capability not supported. |
140| 17700001 | The specified bundle name is not found. |
141| 17700002 | The specified module name is not found. |
142
143**Example**
144
145```js
146import freeInstall from '@ohos.bundle.freeInstall';
147import { BusinessError } from '@ohos.base';
148let bundleName = 'com.example.myapplication';
149let moduleName = 'entry';
150let upgradeFlag = freeInstall.UpgradeFlag.SINGLE_UPGRADE;
151try {
152    freeInstall.setHapModuleUpgradeFlag(bundleName, moduleName, upgradeFlag).then(() => {
153        console.info('Operation succeed')
154    }).catch((err: BusinessError) => {
155        console.error('Operation failed:' + JSON.stringify(err));
156    });
157} catch (err) {
158    console.error('Operation failed:' + JSON.stringify(err));
159}
160```
161
162## isHapModuleRemovable
163
164isHapModuleRemovable(bundleName: string, moduleName: string, callback: AsyncCallback\<boolean>): void
165
166Checks whether a module can be removed. This API uses an asynchronous callback to return the result.
167
168**System API**: This is a system API.
169
170**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
171
172**System capability**: SystemCapability.BundleManager.BundleFramework.FreeInstall
173
174**Parameters**
175
176| Name     | Type                  | Mandatory | Description                                         |
177| ---------- | ---------------------- | ---- | --------------------------------------------- |
178| bundleName | string                 | Yes  | Bundle name.                     |
179| moduleName | string                 | Yes  | Module name.                           |
180| callback   | AsyncCallback\<boolean> | Yes  | Callback used to return the result. If the module can be removed, **true** is returned; otherwise, **false** is returned. |
181
182**Error codes**
183
184For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
185
186| ID |    Error Message                           |
187|----------|----------------------------------------|
188| 201 | Permission denied. |
189| 202 | Permission denied, non-system app called system api. |
190| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
191| 801 | Capability not supported. |
192| 17700001 | The specified bundle name is not found. |
193| 17700002 | The specified module name is not found. |
194
195**Example**
196
197```js
198import freeInstall from '@ohos.bundle.freeInstall';
199let bundleName = 'com.example.myapplication';
200let moduleName = 'entry';
201try {
202    freeInstall.isHapModuleRemovable(bundleName, moduleName, (err, data) => {
203        if (err) {
204            console.error('Operation failed:' + JSON.stringify(err));
205        } else {
206            console.info('Operation succeed:' + JSON.stringify(data));
207        }
208    });
209} catch (err) {
210    console.error('Operation failed:' + JSON.stringify(err));
211}
212```
213
214## isHapModuleRemovable
215
216isHapModuleRemovable(bundleName: string, moduleName: string): Promise\<boolean>
217
218Checks whether a module can be removed. This API uses a promise to return the result.
219
220**System API**: This is a system API.
221
222**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
223
224**System capability**: SystemCapability.BundleManager.BundleFramework.FreeInstall
225
226**Parameters**
227
228| Name    | Type  | Mandatory | Description              |
229| ---------- | ------ | ---- | ------------------ |
230| bundleName | string | Yes  | Bundle name.  |
231| moduleName | string | Yes  | Module name. |
232
233**Return value**
234
235| Type            | Description                        |
236| ---------------- | ---------------------------- |
237| Promise\<boolean> | Promise used to return the result. If the module can be removed, **true** is returned; otherwise, **false** is returned. |
238
239**Error codes**
240
241For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
242
243| ID |    Error Message                           |
244|----------|----------------------------------------|
245| 201 | Permission denied. |
246| 202 | Permission denied, non-system app called system api. |
247| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
248| 801 | Capability not supported. |
249| 17700001 | The specified bundle name is not found. |
250| 17700002 | The specified module name is not found. |
251
252**Example**
253
254```js
255import freeInstall from '@ohos.bundle.freeInstall';
256import { BusinessError } from '@ohos.base';
257let bundleName = 'com.example.myapplication';
258let moduleName = 'entry';
259try {
260    freeInstall.isHapModuleRemovable(bundleName, moduleName).then(data => {
261        console.info('Operation succeed:' + JSON.stringify(data));
262    }).catch((err: BusinessError) => {
263        console.error('Operation failed:' + JSON.stringify(err));
264    });
265} catch (err) {
266    console.error('Operation failed:' + JSON.stringify(err));
267}
268```
269
270## getBundlePackInfo
271
272getBundlePackInfo(bundleName: string, bundlePackFlag : BundlePackFlag, callback: AsyncCallback\<BundlePackInfo>): void
273
274Obtains **bundlePackInfo** based on **bundleName** and **bundlePackFlag**. This API uses an asynchronous callback to return the result.
275
276**System API**: This is a system API.
277
278**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
279
280**System capability**: SystemCapability.BundleManager.BundleFramework.FreeInstall
281
282**Parameters**
283
284| Name        | Type                                                        | Mandatory | Description                                                        |
285| -------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
286| bundleName     | string                                                       | Yes  | Bundle name.                                            |
287| bundlePackFlag | [BundlePackFlag](#bundlepackflag)                            | Yes  | Flag of the bundle package.                                    |
288| callback       | AsyncCallback<[BundlePackInfo](js-apis-bundleManager-BundlePackInfo-sys.md)> | Yes  | Callback used to return the result. If the operation is successful, **err** is **null** and **data** is the **BundlePackInfo** object obtained; otherwise, **err** is an error object. |
289
290**Error codes**
291
292For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
293
294| ID |    Error Message                           |
295|----------|----------------------------------------|
296| 201 | Permission denied. |
297| 202 | Permission denied, non-system app called system api. |
298| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
299| 801 | Capability not supported. |
300| 17700001 | The specified bundle name is not found. |
301
302**Example**
303
304```js
305import freeInstall from '@ohos.bundle.freeInstall';
306let bundleName = 'com.example.myapplication';
307let bundlePackFlag = freeInstall.BundlePackFlag.GET_PACK_INFO_ALL;
308try {
309    freeInstall.getBundlePackInfo(bundleName, bundlePackFlag, (err, data) => {
310        if (err) {
311            console.error('Operation failed:' + JSON.stringify(err));
312        } else {
313            console.info('Operation succeed:' + JSON.stringify(data));
314        }
315    });
316} catch (err) {
317    console.error('Operation failed:' + JSON.stringify(err));
318}
319```
320## getBundlePackInfo
321
322getBundlePackInfo(bundleName: string, bundlePackFlag : BundlePackFlag): Promise\<BundlePackInfo>
323
324Obtains **bundlePackInfo** based on **bundleName** and **bundlePackFlag**. This API uses a promise to return the result.
325
326**System API**: This is a system API.
327
328**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
329
330**System capability**: SystemCapability.BundleManager.BundleFramework.FreeInstall
331
332**Parameters**
333
334| Name        | Type                             | Mandatory | Description                  |
335| -------------- | --------------------------------- | ---- | ---------------------- |
336| bundleName     | string                            | Yes  | Bundle name. |
337| bundlePackFlag | [BundlePackFlag](#bundlepackflag) | Yes  | Flag of the bundle package.|
338
339**Return value**
340
341| Type                                                      | Description                               |
342| ---------------------------------------------------------- | ----------------------------------- |
343| Promise<[BundlePackInfo](js-apis-bundleManager-BundlePackInfo-sys.md)> | Promise used to return the **BundlePackInfo** object obtained. |
344
345**Error codes**
346
347For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
348
349| ID |    Error Message                           |
350|----------|----------------------------------------|
351| 201 | Permission denied. |
352| 202 | Permission denied, non-system app called system api. |
353| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
354| 801 | Capability not supported. |
355| 17700001 | The specified bundle name is not found. |
356
357**Example**
358
359```js
360import freeInstall from '@ohos.bundle.freeInstall';
361import { BusinessError } from '@ohos.base';
362let bundleName = 'com.example.myapplication';
363let bundlePackFlag = freeInstall.BundlePackFlag.GET_PACK_INFO_ALL;
364try {
365    freeInstall.getBundlePackInfo(bundleName, bundlePackFlag).then(data => {
366        console.info('Operation succeed:' + JSON.stringify(data));
367    }).catch((err: BusinessError) => {
368        console.error('Operation failed:' + JSON.stringify(err));
369    });
370} catch (err) {
371    console.error('Operation failed:' + JSON.stringify(err));
372}
373```
374
375## getDispatchInfo
376
377getDispatchInfo(callback: AsyncCallback\<DispatchInfo>): void
378
379Obtains the dispatch information. This API uses an asynchronous callback to return the result.
380
381**System API**: This is a system API.
382
383**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
384
385**System capability**: SystemCapability.BundleManager.BundleFramework.FreeInstall
386
387**Parameters**
388
389| Name  | Type                                                        | Mandatory | Description                                                        |
390| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
391| callback | AsyncCallback<[DispatchInfo](js-apis-bundleManager-dispatchInfo-sys.md)> | Yes  | Callback used to return the result. If the operation is successful, **err** is **null**, and **data** is the [DispatchInfo](js-apis-bundleManager-dispatchInfo-sys.md) object obtained. otherwise, **err** is an error object. |
392
393**Error codes**
394
395For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
396
397| ID |    Error Message                           |
398|----------|----------------------------------------|
399| 201 | Permission denied. |
400| 202 | Permission denied, non-system app called system api. |
401| 801 | Capability not supported. |
402
403**Example**
404
405```js
406import freeInstall from '@ohos.bundle.freeInstall';
407try {
408    freeInstall.getDispatchInfo((err, data) => {
409        if (err) {
410            console.error('Operation failed:' + JSON.stringify(err));
411        } else {
412            console.info('Operation succeed:' + JSON.stringify(data));
413        }
414    });
415} catch (err) {
416    console.error('Operation failed:' + JSON.stringify(err));
417}
418```
419
420## getDispatchInfo
421
422getDispatchInfo(): Promise\<DispatchInfo>
423
424Obtains the dispatch information. This API uses a promise to return the result.
425
426**System API**: This is a system API.
427
428**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
429
430**System capability**: SystemCapability.BundleManager.BundleFramework.FreeInstall
431
432**Return value**
433
434| Type                                            | Description                                                        |
435| ------------------------------------------------ | ------------------------------------------------------------ |
436| Promise<[DispatchInfo](js-apis-bundleManager-dispatchInfo-sys.md)> | Promise used to return the [DispatchInfo](js-apis-bundleManager-dispatchInfo-sys.md) object obtained. |
437
438**Error codes**
439
440For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
441
442| ID |    Error Message                           |
443|----------|----------------------------------------|
444| 201 | Permission denied. |
445| 202 | Permission denied, non-system app called system api. |
446| 801 | Capability not supported. |
447
448**Example**
449
450```js
451import freeInstall from '@ohos.bundle.freeInstall';
452import { BusinessError } from '@ohos.base';
453try {
454    freeInstall.getDispatchInfo().then(data => {
455        console.info('Operation succeed:' + JSON.stringify(data));
456    }).catch((err: BusinessError) => {
457        console.error('Operation failed:' + JSON.stringify(err));
458    });
459} catch (err) {
460    console.error('Operation failed:' + JSON.stringify(err));
461}
462```
463