1# @ohos.bundle.freeInstall (freeInstall模块)(系统接口)
2
3本模块提供免安装相关的设置和查询能力，支持BundlePackInfo、DispatchInfo等信息的查询。
4
5> **说明：**
6>
7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> 本模块为系统接口。
10
11## 导入模块
12
13```js
14import freeInstall from '@ohos.bundle.freeInstall';
15```
16
17## 权限列表
18
19| 权限                                       | 权限等级     | 描述               |
20| ------------------------------------------ | ------------ | ------------------ |
21| ohos.permission.GET_BUNDLE_INFO_PRIVILEGED | system_basic | 可查询所有应用信息。 |
22| ohos.permission.INSTALL_BUNDLE             | system_core  | 允许应用安装、卸载其他应用（除了企业相关应用，目前有企业InHouse应用，企业MDM应用和企业normal应用）。   |
23
24权限等级参考[权限APL等级说明](../../security/AccessToken/app-permission-mgmt-overview.md#权限机制中的基本概念)。
25## UpgradeFlag
26
27**系统接口：** 此接口为系统接口。
28
29**系统能力：** SystemCapability.BundleManager.BundleFramework.FreeInstall
30
31| 名称             | 值   | 说明             |
32| ---------------- | ---- | ---------------- |
33| NOT_UPGRADE      | 0    | 模块无需升级。     |
34| SINGLE_UPGRADE   | 1    | 单个模块需要升级。 |
35| RELATION_UPGRADE | 2    | 关系模块需要升级。 |
36
37## BundlePackFlag
38
39**系统接口：** 此接口为系统接口。
40
41**系统能力：** SystemCapability.BundleManager.BundleFramework.FreeInstall
42
43| 名称               | 值         | 说明                               |
44| ------------------ | ---------- | ---------------------------------- |
45| GET_PACK_INFO_ALL  | 0x00000000 | 获取应用包pack.info的所有信息。    |
46| GET_PACKAGES       | 0x00000001 | 获取应用包pack.info的package信息。 |
47| GET_BUNDLE_SUMMARY | 0x00000002 | 获取应用包pack.info的bundle摘要信息。  |
48| GET_MODULE_SUMMARY | 0x00000004 | 获取应用包pack.info的module摘要信息。  |
49
50## freeInstall.setHapModuleUpgradeFlag
51
52setHapModuleUpgradeFlag(bundleName: string, moduleName: string, upgradeFlag: UpgradeFlag, callback: AsyncCallback\<void>):void
53
54设置指定模块是否升级。使用callback异步回调。
55
56**需要权限：** ohos.permission.INSTALL_BUNDLE
57
58**系统接口：** 此接口为系统接口。
59
60**系统能力：** SystemCapability.BundleManager.BundleFramework.FreeInstall
61
62**参数：**
63
64| 参数名     | 类型                        | 必填 | 说明                       |
65| ----------- | --------------------------- | ---- | ---------------------------- |
66| bundleName  | string                      | 是   | 应用Bundle名称。     |
67| moduleName  | string                      | 是   | 应用程序模块名称。           |
68| upgradeFlag | [UpgradeFlag](#upgradeflag) | 是   | 仅供内部系统使用标志位       |
69| callback    | AsyncCallback\<void>        | 是   | 回调函数。当函数调用成功，err为null，否则为错误对象。 |
70
71**错误码：**
72
73以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
74
75| 错误码ID |    错误信息                            |
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**示例：**
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
108设置指定模块是否升级。使用Promise异步回调。
109
110**系统接口：** 此接口为系统接口。
111
112**需要权限：** ohos.permission.INSTALL_BUNDLE
113
114**系统能力：** SystemCapability.BundleManager.BundleFramework.FreeInstall
115
116**参数：**
117
118| 参数名      | 类型                        | 必填 | 说明                   |
119| ----------- | --------------------------- | ---- | ---------------------- |
120| bundleName  | string                      | 是   | 应用Bundle名称。 |
121| moduleName  | string                      | 是   | 应用程序模块名称。     |
122| upgradeFlag | [UpgradeFlag](#upgradeflag) | 是   | 仅供内部系统使用标志位。|
123
124**返回值：**
125
126| 类型          | 说明                                 |
127| ------------- | ------------------------------------ |
128| Promise\<void> | Promise对象。无返回结果的Promise对象。 |
129
130**错误码：**
131
132以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
133
134| 错误码ID |    错误信息                            |
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**示例：**
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
166查询指定模块是否可以被移除。使用callback异步回调。
167
168**系统接口：** 此接口为系统接口。
169
170**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
171
172**系统能力：** SystemCapability.BundleManager.BundleFramework.FreeInstall
173
174**参数：**
175
176| 参数名      | 类型                   | 必填 | 说明                                          |
177| ---------- | ---------------------- | ---- | --------------------------------------------- |
178| bundleName | string                 | 是   | 应用Bundle名称。                      |
179| moduleName | string                 | 是   | 应用程序模块名称。                            |
180| callback   | AsyncCallback\<boolean> | 是   | 回调函数。返回true表示可以移除；返回false表示不可移除。 |
181
182**错误码：**
183
184以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
185
186| 错误码ID |    错误信息                            |
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**示例：**
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
218查询指定模块是否可以被移除。使用Promise异步回调。
219
220**系统接口：** 此接口为系统接口。
221
222**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
223
224**系统能力：** SystemCapability.BundleManager.BundleFramework.FreeInstall
225
226**参数：**
227
228| 参数名     | 类型   | 必填 | 说明               |
229| ---------- | ------ | ---- | ------------------ |
230| bundleName | string | 是   | 应用Bundle名称。   |
231| moduleName | string | 是   | 应用程序模块名称。 |
232
233**返回值：**
234
235| 类型             | 说明                         |
236| ---------------- | ---------------------------- |
237| Promise\<boolean> | Promise对象。返回true表示可以移除；返回false表示不可移除。 |
238
239**错误码：**
240
241以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
242
243| 错误码ID |    错误信息                            |
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**示例：**
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
274基于bundleName和bundlePackFlag来获取bundlePackInfo。使用callback异步回调。
275
276**系统接口：** 此接口为系统接口。
277
278**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
279
280**系统能力：** SystemCapability.BundleManager.BundleFramework.FreeInstall
281
282**参数：**
283
284| 参数名         | 类型                                                         | 必填 | 说明                                                         |
285| -------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
286| bundleName     | string                                                       | 是   | 应用Bundle名称。                                             |
287| bundlePackFlag | [BundlePackFlag](#bundlepackflag)                            | 是   | 指示要查询的应用包标志。                                     |
288| callback       | AsyncCallback<[BundlePackInfo](js-apis-bundleManager-BundlePackInfo-sys.md)> | 是   | 回调函数。当函数调用成功，err为null，data为获取到的BundlePackInfo信息。否则为错误对象。 |
289
290**错误码：**
291
292以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
293
294| 错误码ID |    错误信息                            |
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**示例：**
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
324基于bundleName和BundlePackFlag来获取bundlePackInfo。使用Promise异步回调。
325
326**系统接口：** 此接口为系统接口。
327
328**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
329
330**系统能力：** SystemCapability.BundleManager.BundleFramework.FreeInstall
331
332**参数：**
333
334| 参数名         | 类型                              | 必填 | 说明                   |
335| -------------- | --------------------------------- | ---- | ---------------------- |
336| bundleName     | string                            | 是   | 应用程序Bundle名称。 |
337| bundlePackFlag | [BundlePackFlag](#bundlepackflag) | 是   | 指示要查询的应用包标志。|
338
339**返回值：**
340
341| 类型                                                       | 说明                                |
342| ---------------------------------------------------------- | ----------------------------------- |
343| Promise<[BundlePackInfo](js-apis-bundleManager-BundlePackInfo-sys.md)> | Promise对象，返回BundlePackInfo信息。 |
344
345**错误码：**
346
347以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
348
349| 错误码ID |    错误信息                            |
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**示例：**
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
379获取有关dispatch版本的信息。使用callback异步回调。
380
381**系统接口：** 此接口为系统接口。
382
383**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
384
385**系统能力：** SystemCapability.BundleManager.BundleFramework.FreeInstall
386
387**参数：**
388
389| 参数名   | 类型                                                         | 必填 | 说明                                                         |
390| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
391| callback | AsyncCallback<[DispatchInfo](js-apis-bundleManager-dispatchInfo-sys.md)> | 是   | 回调函数。当函数调用成功，err为null，data为获取到的[DispatchInfo](js-apis-bundleManager-dispatchInfo-sys.md)信息。否则为错误对象。 |
392
393**错误码：**
394
395以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
396
397| 错误码ID |    错误信息                            |
398|----------|----------------------------------------|
399| 201 | Permission denied. |
400| 202 | Permission denied, non-system app called system api. |
401| 801 | Capability not supported. |
402
403**示例：**
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
424获取有关dispatch版本的信息。使用Promise异步回调。
425
426**系统接口：** 此接口为系统接口。
427
428**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
429
430**系统能力：** SystemCapability.BundleManager.BundleFramework.FreeInstall
431
432**返回值：**
433
434| 类型                                             | 说明                                                         |
435| ------------------------------------------------ | ------------------------------------------------------------ |
436| Promise<[DispatchInfo](js-apis-bundleManager-dispatchInfo-sys.md)> | Promise对象，返回[DispatchInfo](js-apis-bundleManager-dispatchInfo-sys.md)信息。 |
437
438**错误码：**
439
440以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
441
442| 错误码ID |    错误信息                            |
443|----------|----------------------------------------|
444| 201 | Permission denied. |
445| 202 | Permission denied, non-system app called system api. |
446| 801 | Capability not supported. |
447
448**示例：**
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